Skip to main content

ftui_widgets/
list.rs

1#![forbid(unsafe_code)]
2
3//! List widget.
4//!
5//! A widget to display a list of items with selection support.
6
7use crate::block::Block;
8use crate::measurable::{MeasurableWidget, SizeConstraints};
9use crate::mouse::MouseResult;
10use crate::stateful::{StateKey, Stateful};
11use crate::undo_support::{ListUndoExt, UndoSupport, UndoWidgetId};
12use crate::{
13    StatefulWidget, Widget, clear_text_area, clear_text_row, draw_text_span,
14    draw_text_span_with_link,
15};
16use ftui_core::event::{
17    KeyCode, KeyEvent, KeyEventKind, Modifiers, MouseButton, MouseEvent, MouseEventKind,
18};
19use ftui_core::geometry::{Rect, Size};
20use ftui_core::hover_stabilizer::{HoverStabilizer, HoverStabilizerConfig};
21use ftui_render::frame::{Frame, HitId, HitRegion};
22use ftui_style::Style;
23use ftui_text::{Line, Span, Text as FtuiText, display_width};
24use std::collections::BTreeSet;
25#[cfg(feature = "tracing")]
26use web_time::Instant;
27
28type Text = FtuiText<'static>;
29
30fn text_into_owned(text: FtuiText<'_>) -> FtuiText<'static> {
31    FtuiText::from_lines(
32        text.into_iter()
33            .map(|line| Line::from_spans(line.into_iter().map(Span::into_owned))),
34    )
35}
36
37/// A single item in a list.
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct ListItem<'a> {
40    content: Text,
41    style: Style,
42    marker: &'a str,
43}
44
45impl<'a> ListItem<'a> {
46    /// Create a new list item with the given content.
47    #[must_use]
48    pub fn new<'t>(content: impl Into<FtuiText<'t>>) -> Self {
49        Self {
50            content: text_into_owned(content.into()),
51            style: Style::default(),
52            marker: "",
53        }
54    }
55
56    /// Set the style for this list item.
57    #[must_use]
58    pub fn style(mut self, style: Style) -> Self {
59        self.style = style;
60        self
61    }
62
63    /// Set a prefix marker string for this item.
64    #[must_use]
65    pub fn marker(mut self, marker: &'a str) -> Self {
66        self.marker = marker;
67        self
68    }
69}
70
71impl<'a> From<&'a str> for ListItem<'a> {
72    fn from(s: &'a str) -> Self {
73        Self::new(s)
74    }
75}
76
77/// A widget to display a list of items.
78#[derive(Debug, Clone, Default)]
79pub struct List<'a> {
80    block: Option<Block<'a>>,
81    items: Vec<ListItem<'a>>,
82    style: Style,
83    highlight_style: Style,
84    hover_style: Style,
85    highlight_symbol: Option<&'a str>,
86    /// Optional hit ID for mouse interaction.
87    /// When set, each list item registers a hit region with the hit grid.
88    hit_id: Option<HitId>,
89    /// Optional data hash to enable caching of filtered indices.
90    data_hash: Option<u64>,
91    /// Optional stable accessibility identity for this list.
92    accessibility_id: Option<u64>,
93}
94
95impl<'a> List<'a> {
96    /// Create a new list from the given items.
97    #[must_use]
98    pub fn new(items: impl IntoIterator<Item = impl Into<ListItem<'a>>>) -> Self {
99        Self {
100            block: None,
101            items: items.into_iter().map(|i| i.into()).collect(),
102            style: Style::default(),
103            highlight_style: Style::default(),
104            hover_style: Style::default(),
105            highlight_symbol: None,
106            hit_id: None,
107            data_hash: None,
108            accessibility_id: None,
109        }
110    }
111
112    /// Give this list a stable accessibility identity.
113    #[must_use]
114    pub fn accessibility_id(mut self, id: u64) -> Self {
115        self.accessibility_id = Some(id);
116        self
117    }
118
119    /// Set an explicit data hash to enable caching of filtered indices.
120    ///
121    /// This is highly recommended for large lists. When provided, the list widget
122    /// will cache the result of filtering in the `ListState`, skipping expensive
123    /// O(N) string processing on frames where the hash and filter query have not changed.
124    #[must_use]
125    pub fn data_hash(mut self, hash: u64) -> Self {
126        self.data_hash = Some(hash);
127        self
128    }
129
130    /// Wrap the list in a decorative block.
131    #[must_use]
132    pub fn block(mut self, block: Block<'a>) -> Self {
133        self.block = Some(block);
134        self
135    }
136
137    /// Set the base style for the list area.
138    #[must_use]
139    pub fn style(mut self, style: Style) -> Self {
140        self.style = style;
141        self
142    }
143
144    /// Set the style applied to the selected item.
145    #[must_use]
146    pub fn highlight_style(mut self, style: Style) -> Self {
147        self.highlight_style = style;
148        self
149    }
150
151    /// Set the style applied to the hovered item (mouse move).
152    #[must_use]
153    pub fn hover_style(mut self, style: Style) -> Self {
154        self.hover_style = style;
155        self
156    }
157
158    /// Set a symbol displayed before the selected item.
159    #[must_use]
160    pub fn highlight_symbol(mut self, symbol: &'a str) -> Self {
161        self.highlight_symbol = Some(symbol);
162        self
163    }
164
165    /// Set a hit ID for mouse interaction.
166    ///
167    /// When set, each list item will register a hit region with the frame's
168    /// hit grid (if enabled). The hit data will be the item's index, allowing
169    /// click handlers to determine which item was clicked.
170    #[must_use]
171    pub fn hit_id(mut self, id: HitId) -> Self {
172        self.hit_id = Some(id);
173        self
174    }
175
176    fn accessibility_root_id(&self, area: Rect) -> u64 {
177        if let Some(id) = self.accessibility_id {
178            return id;
179        }
180        if let Some(hit) = self.hit_id {
181            use std::hash::{Hash, Hasher};
182            let mut hasher = std::collections::hash_map::DefaultHasher::new();
183            ("ftui.list.hit", hit.id()).hash(&mut hasher);
184            return hasher.finish();
185        }
186        crate::a11y_node_id(area)
187    }
188
189    fn accessibility_item_id(parent: u64, index: usize) -> u64 {
190        use std::hash::{Hash, Hasher};
191        let mut hasher = std::collections::hash_map::DefaultHasher::new();
192        ("ftui.list.item", parent, index).hash(&mut hasher);
193        hasher.finish()
194    }
195
196    fn push_stateful_accessibility(
197        &self,
198        list_area: Rect,
199        frame: &mut Frame,
200        state: &ListState,
201        filtered: &[usize],
202    ) {
203        if !frame.a11y_enabled() || list_area.is_empty() {
204            return;
205        }
206        let bounds = list_area.intersection(&frame.buffer.current_scissor());
207        if bounds.is_empty() {
208            return;
209        }
210        let root_id = self.accessibility_root_id(list_area);
211        let title = self
212            .block
213            .as_ref()
214            .and_then(|block| block.title_text())
215            .filter(|title| !title.trim().is_empty())
216            .unwrap_or("List");
217        let description = if state.filter_query.trim().is_empty() {
218            format!("{} items", filtered.len())
219        } else {
220            format!("{} matching items", filtered.len())
221        };
222        let root =
223            ftui_a11y::node::A11yNodeInfo::new(root_id, ftui_a11y::node::A11yRole::List, bounds)
224                .with_name(title)
225                .with_description(description);
226        frame.with_a11y_scope(root, |frame| {
227            let visible_end = (state.offset + list_area.height as usize).min(filtered.len());
228            for (row, item_index) in filtered[state.offset.min(filtered.len())..visible_end]
229                .iter()
230                .enumerate()
231            {
232                let item = &self.items[*item_index];
233                let y = list_area.y.saturating_add(row as u16);
234                let item_bounds = Rect::new(list_area.x, y, list_area.width, 1)
235                    .intersection(&frame.buffer.current_scissor());
236                if item_bounds.is_empty() {
237                    continue;
238                }
239                let item_text = item
240                    .content
241                    .lines()
242                    .first()
243                    .map(|line| line.to_plain_text())
244                    .unwrap_or_default();
245                let mut node = ftui_a11y::node::A11yNodeInfo::new(
246                    Self::accessibility_item_id(root_id, *item_index),
247                    ftui_a11y::node::A11yRole::ListItem,
248                    item_bounds,
249                );
250                if !item_text.is_empty() {
251                    node.name = Some(item_text);
252                }
253                node.state.selected = state.selected == Some(*item_index)
254                    || (state.multi_select_enabled && state.multi_selected.contains(item_index));
255                node.state.focused = state.focused && state.selected == Some(*item_index);
256                frame.push_a11y(node);
257            }
258        });
259    }
260
261    fn filtered_indices(&self, state: &mut ListState) -> std::sync::Arc<[usize]> {
262        let query_str = state.filter_query();
263
264        if let Some(hash) = self.data_hash
265            && let Some((cached_hash, ref cached_query, ref indices)) = state.cached_display_indices
266            && cached_hash == hash
267            && cached_query == query_str
268        {
269            return std::sync::Arc::clone(indices);
270        }
271
272        let query = query_str.trim();
273        let indices: Vec<usize> = if query.is_empty() {
274            (0..self.items.len()).collect()
275        } else {
276            let query_lower = query.to_lowercase();
277            self.items
278                .iter()
279                .enumerate()
280                .filter_map(|(idx, item)| {
281                    // Optimization: check single-span content directly to avoid allocation
282                    // from to_plain_text().
283                    let line_text_cow;
284                    let line_text_ref = if let Some(line) = item.content.lines().first() {
285                        if line.spans().len() == 1 {
286                            &line.spans()[0].content
287                        } else {
288                            line_text_cow = std::borrow::Cow::Owned(line.to_plain_text());
289                            &line_text_cow
290                        }
291                    } else {
292                        ""
293                    };
294
295                    let marker_matches = !item.marker.is_empty()
296                        && crate::contains_ignore_case(item.marker, &query_lower);
297                    if marker_matches || crate::contains_ignore_case(line_text_ref, &query_lower) {
298                        Some(idx)
299                    } else {
300                        None
301                    }
302                })
303                .collect()
304        };
305
306        let arc_indices: std::sync::Arc<[usize]> = indices.into();
307
308        if let Some(hash) = self.data_hash {
309            state.cached_display_indices = Some((
310                hash,
311                query_str.to_string(),
312                std::sync::Arc::clone(&arc_indices),
313            ));
314        }
315
316        arc_indices
317    }
318
319    fn apply_filtered_selection_guard(
320        &self,
321        state: &mut ListState,
322        filtered: &[usize],
323        force_select_first: bool,
324    ) {
325        if filtered.is_empty() {
326            state.selected = None;
327            state.hovered = None;
328            state.offset = 0;
329            state.multi_selected.clear();
330            return;
331        }
332
333        if let Some(selected) = state.selected {
334            if filtered.binary_search(&selected).is_err() {
335                state.selected = filtered.first().copied();
336            }
337        } else if force_select_first {
338            state.selected = filtered.first().copied();
339        }
340
341        state
342            .multi_selected
343            .retain(|idx| filtered.binary_search(idx).is_ok());
344    }
345
346    fn move_selection_in_filtered(
347        &self,
348        state: &mut ListState,
349        filtered: &[usize],
350        direction: isize,
351    ) -> bool {
352        if filtered.is_empty() {
353            if state.selected.is_some() {
354                state.select(None);
355                return true;
356            }
357            return false;
358        }
359
360        let max_pos = filtered.len().saturating_sub(1) as isize;
361
362        let next_pos = if let Some(selected) = state.selected {
363            // `filtered` is sorted by index (ascending), so we can use binary search
364            // for O(log N) lookup instead of O(N) linear scan.
365            let current_pos = filtered.binary_search(&selected).unwrap_or_else(|pos| pos);
366            (current_pos as isize + direction).clamp(0, max_pos) as usize
367        } else if direction > 0 {
368            0
369        } else {
370            max_pos as usize
371        };
372
373        let next_index = filtered[next_pos];
374
375        if state.selected == Some(next_index) {
376            return false;
377        }
378
379        state.selected = Some(next_index);
380        if !state.multi_select_enabled {
381            state.multi_selected.clear();
382            state.multi_selected.insert(next_index);
383        }
384        state.scroll_into_view_requested = true;
385        #[cfg(feature = "tracing")]
386        state.log_selection_change("keyboard_move");
387        true
388    }
389
390    /// Handle keyboard navigation and incremental filtering for this list.
391    ///
392    /// Supported keys:
393    /// - Navigation: `Up`/`Down`, `k`/`j` (vi-style, always navigate — never
394    ///   appended to the filter query)
395    /// - Incremental filter input: printable chars (except `j`/`k`)
396    /// - Filter editing: `Backspace`, `Escape`
397    /// - Multi-select toggle (when enabled): `Space`
398    ///
399    /// Acts on press and repeat, never release. With release events reported
400    /// (kitty keyboard protocol, web backend), each key acted twice: a typed
401    /// "a" filtered for "aa" and every arrow moved two rows.
402    pub fn handle_key(&self, state: &mut ListState, key: &KeyEvent) -> bool {
403        if key.kind == KeyEventKind::Release {
404            return false;
405        }
406        let nav_modifiers = key
407            .modifiers
408            .intersects(Modifiers::CTRL | Modifiers::ALT | Modifiers::SUPER);
409
410        match key.code {
411            KeyCode::Up if !nav_modifiers => {
412                let filtered = self.filtered_indices(state);
413                self.move_selection_in_filtered(state, &filtered, -1)
414            }
415            KeyCode::Down if !nav_modifiers => {
416                let filtered = self.filtered_indices(state);
417                self.move_selection_in_filtered(state, &filtered, 1)
418            }
419            // j/k are always vi-style navigation, even when a filter is active.
420            KeyCode::Char('k') if !nav_modifiers => {
421                let filtered = self.filtered_indices(state);
422                self.move_selection_in_filtered(state, &filtered, -1)
423            }
424            KeyCode::Char('j') if !nav_modifiers => {
425                let filtered = self.filtered_indices(state);
426                self.move_selection_in_filtered(state, &filtered, 1)
427            }
428            KeyCode::Char(' ') if state.multi_select_enabled() => {
429                if let Some(selected) = state.selected {
430                    state.toggle_multi_selected(selected);
431                    true
432                } else {
433                    false
434                }
435            }
436            KeyCode::Backspace => {
437                if state.filter_query.is_empty() {
438                    return false;
439                }
440                state.filter_query.pop();
441                state.offset = 0;
442                state.scroll_into_view_requested = true;
443                let filtered = self.filtered_indices(state);
444                self.apply_filtered_selection_guard(state, &filtered, true);
445                #[cfg(feature = "tracing")]
446                state.log_selection_change("filter_backspace");
447                true
448            }
449            KeyCode::Escape => {
450                if state.filter_query.is_empty() {
451                    return false;
452                }
453                state.filter_query.clear();
454                state.offset = 0;
455                state.scroll_into_view_requested = true;
456                let filtered = self.filtered_indices(state);
457                self.apply_filtered_selection_guard(state, &filtered, false);
458                #[cfg(feature = "tracing")]
459                state.log_selection_change("filter_clear");
460                true
461            }
462            KeyCode::Char(ch)
463                if !ch.is_control() && !key.ctrl() && !key.alt() && !key.super_key() =>
464            {
465                // Preserve uppercase input when Shift is held.
466                state.filter_query.push(ch);
467                state.offset = 0;
468                state.scroll_into_view_requested = true;
469                let filtered = self.filtered_indices(state);
470                self.apply_filtered_selection_guard(state, &filtered, true);
471                #[cfg(feature = "tracing")]
472                state.log_selection_change("filter_append");
473                true
474            }
475            _ => false,
476        }
477    }
478}
479
480/// Mutable state for a [`List`] widget tracking selection and scroll offset.
481#[derive(Debug, Clone)]
482pub struct ListState {
483    /// Unique ID for undo tracking.
484    undo_id: UndoWidgetId,
485    /// Index of the currently selected item, if any.
486    pub selected: Option<usize>,
487    /// Index of the currently hovered item, if any.
488    pub hovered: Option<usize>,
489    /// Optional CUSUM hover stabilizer (see [`ListState::with_hover_stabilizer`]).
490    hover_stabilizer: Option<HoverStabilizer>,
491    /// Scroll offset (first visible item index).
492    pub offset: usize,
493    /// Optional persistence ID for state saving/restoration.
494    persistence_id: Option<String>,
495    /// Whether to force the selected item into view on next render.
496    scroll_into_view_requested: bool,
497    /// Incremental filter query applied to items (case-insensitive).
498    filter_query: String,
499    /// Whether multi-select behavior is enabled.
500    multi_select_enabled: bool,
501    /// Set of selected indices when multi-select is enabled.
502    multi_selected: BTreeSet<usize>,
503    /// Cached display indices (data_hash, filter_query, indices)
504    #[doc(hidden)]
505    pub cached_display_indices: Option<(u64, String, std::sync::Arc<[usize]>)>,
506    /// Whether this list currently owns keyboard focus.
507    pub focused: bool,
508}
509
510impl Default for ListState {
511    fn default() -> Self {
512        Self {
513            undo_id: UndoWidgetId::default(),
514            selected: None,
515            hovered: None,
516            hover_stabilizer: None,
517            offset: 0,
518            persistence_id: None,
519            scroll_into_view_requested: true,
520            filter_query: String::new(),
521            multi_select_enabled: false,
522            multi_selected: BTreeSet::new(),
523            cached_display_indices: None,
524            focused: false,
525        }
526    }
527}
528
529impl ListState {
530    /// Set the selected item index, or `None` to deselect.
531    pub fn select(&mut self, index: Option<usize>) {
532        self.selected = index;
533        if index.is_none() {
534            self.offset = 0;
535            self.multi_selected.clear();
536        } else if !self.multi_select_enabled
537            && let Some(selected) = index
538        {
539            self.multi_selected.clear();
540            self.multi_selected.insert(selected);
541        }
542        self.scroll_into_view_requested = true;
543        #[cfg(feature = "tracing")]
544        self.log_selection_change("select");
545    }
546
547    /// Return the currently selected item index.
548    #[inline]
549    #[must_use = "use the selected index (if any)"]
550    pub fn selected(&self) -> Option<usize> {
551        self.selected
552    }
553
554    /// Mark whether this list currently owns keyboard focus.
555    pub fn set_focused(&mut self, focused: bool) {
556        self.focused = focused;
557    }
558
559    /// Builder for keyboard focus ownership.
560    #[must_use]
561    pub fn with_focused(mut self, focused: bool) -> Self {
562        self.focused = focused;
563        self
564    }
565
566    /// Whether this list currently owns keyboard focus.
567    #[must_use]
568    pub const fn is_focused(&self) -> bool {
569        self.focused
570    }
571
572    /// Create a new ListState with a persistence ID for state saving. Without
573    /// one the list has no [`StateKey`] and its state is not persisted.
574    #[must_use]
575    pub fn with_persistence_id(mut self, id: impl Into<String>) -> Self {
576        self.persistence_id = Some(id.into());
577        self
578    }
579
580    /// Get the persistence ID, if set.
581    #[inline]
582    #[must_use = "use the persistence id (if any)"]
583    pub fn persistence_id(&self) -> Option<&str> {
584        self.persistence_id.as_deref()
585    }
586
587    /// Enable or disable multi-select mode.
588    pub fn set_multi_select(&mut self, enabled: bool) {
589        if self.multi_select_enabled == enabled {
590            return;
591        }
592        self.multi_select_enabled = enabled;
593        if !enabled {
594            self.multi_selected.clear();
595            if let Some(selected) = self.selected {
596                self.multi_selected.insert(selected);
597            }
598        }
599    }
600
601    /// Whether multi-select mode is enabled.
602    #[must_use]
603    pub const fn multi_select_enabled(&self) -> bool {
604        self.multi_select_enabled
605    }
606
607    /// Current incremental filter query.
608    #[must_use]
609    pub fn filter_query(&self) -> &str {
610        &self.filter_query
611    }
612
613    /// Replace the incremental filter query.
614    pub fn set_filter_query(&mut self, query: impl Into<String>) {
615        self.filter_query = query.into();
616        self.offset = 0;
617        self.scroll_into_view_requested = true;
618    }
619
620    /// Clear the current filter query.
621    pub fn clear_filter_query(&mut self) {
622        if !self.filter_query.is_empty() {
623            self.filter_query.clear();
624            self.offset = 0;
625            self.scroll_into_view_requested = true;
626        }
627    }
628
629    /// Number of selected rows (single or multi mode).
630    #[must_use]
631    pub fn selected_count(&self) -> usize {
632        if self.multi_select_enabled {
633            self.multi_selected.len()
634        } else {
635            usize::from(self.selected.is_some())
636        }
637    }
638
639    /// Selected indices in multi-select mode.
640    #[must_use]
641    pub fn selected_indices(&self) -> &BTreeSet<usize> {
642        &self.multi_selected
643    }
644
645    fn toggle_multi_selected(&mut self, index: usize) {
646        if !self.multi_select_enabled {
647            self.select(Some(index));
648            return;
649        }
650        if !self.multi_selected.insert(index) {
651            self.multi_selected.remove(&index);
652        }
653        self.selected = Some(index);
654        self.scroll_into_view_requested = true;
655        #[cfg(feature = "tracing")]
656        self.log_selection_change("toggle_multi");
657    }
658
659    #[cfg(feature = "tracing")]
660    fn log_selection_change(&self, action: &str) {
661        tracing::debug!(
662            message = "list.selection",
663            action,
664            selected = self.selected,
665            selected_count = self.selected_count(),
666            filter_active = !self.filter_query.trim().is_empty()
667        );
668    }
669
670    /// Route hover through a CUSUM hover stabilizer
671    /// ([`ftui_core::hover_stabilizer`]) so one-cell pointer jitter across a
672    /// row boundary keeps the hovered row while a decisive move still
673    /// switches within a frame. Without it, `hovered` follows the raw hit
674    /// test on every mouse move.
675    #[must_use]
676    pub fn with_hover_stabilizer(mut self, config: HoverStabilizerConfig) -> Self {
677        self.hover_stabilizer = Some(HoverStabilizer::new(config));
678        self
679    }
680
681    /// The hover stabilizer, if one is attached (diagnostics such as
682    /// [`HoverStabilizer::switch_count`]).
683    #[must_use]
684    pub fn hover_stabilizer(&self) -> Option<&HoverStabilizer> {
685        self.hover_stabilizer.as_ref()
686    }
687
688    /// Handle a mouse event for this list.
689    ///
690    /// # Hit data convention
691    ///
692    /// The hit data (`u64`) encodes the item index. When the list renders with
693    /// a `hit_id`, each visible row registers `HitRegion::Content` with
694    /// `data = item_index as u64`.
695    ///
696    /// # Arguments
697    ///
698    /// * `event` — the mouse event from the terminal
699    /// * `hit` — result of `frame.hit_test(event.x, event.y)`, if available
700    /// * `expected_id` — the `HitId` this list was rendered with
701    /// * `item_count` — total number of items in the list
702    pub fn handle_mouse(
703        &mut self,
704        event: &MouseEvent,
705        hit: Option<(HitId, HitRegion, u64)>,
706        expected_id: HitId,
707        item_count: usize,
708    ) -> MouseResult {
709        match event.kind {
710            MouseEventKind::Down(MouseButton::Left) => {
711                if let Some((id, HitRegion::Content, data)) = hit
712                    && id == expected_id
713                {
714                    let index = data as usize;
715                    if index < item_count {
716                        if self.multi_select_enabled && event.modifiers.contains(Modifiers::CTRL) {
717                            self.toggle_multi_selected(index);
718                            return MouseResult::Selected(index);
719                        }
720                        if self.multi_select_enabled {
721                            self.multi_selected.clear();
722                            self.multi_selected.insert(index);
723                        }
724                        // Deterministic "double click": second click on the already-selected row activates.
725                        if !self.multi_select_enabled && self.selected == Some(index) {
726                            #[cfg(feature = "tracing")]
727                            self.log_selection_change("activate");
728                            return MouseResult::Activated(index);
729                        }
730                        self.select(Some(index));
731                        return MouseResult::Selected(index);
732                    }
733                }
734                MouseResult::Ignored
735            }
736            MouseEventKind::Moved => {
737                // Raw hit: the row under the pointer, or None when the
738                // pointer is off the widget or on a non-content region.
739                let hit_index = match hit {
740                    Some((id, HitRegion::Content, data))
741                        if id == expected_id && (data as usize) < item_count =>
742                    {
743                        Some(data as usize)
744                    }
745                    _ => None,
746                };
747                let next = match self.hover_stabilizer.as_mut() {
748                    Some(stabilizer) => stabilizer
749                        .update(
750                            hit_index.map(|index| index as u64),
751                            (event.x, event.y),
752                            web_time::Instant::now(),
753                        )
754                        .map(|target| target as usize),
755                    None => hit_index,
756                };
757                let changed = self.hovered != next;
758                self.hovered = next;
759                if changed {
760                    MouseResult::HoverChanged
761                } else {
762                    MouseResult::Ignored
763                }
764            }
765            MouseEventKind::ScrollUp => {
766                self.scroll_up(3);
767                MouseResult::Scrolled
768            }
769            MouseEventKind::ScrollDown => {
770                self.scroll_down(3, item_count);
771                MouseResult::Scrolled
772            }
773            _ => MouseResult::Ignored,
774        }
775    }
776
777    /// Scroll the list up by the given number of lines.
778    pub fn scroll_up(&mut self, lines: usize) {
779        self.offset = self.offset.saturating_sub(lines);
780    }
781
782    /// Scroll the list down by the given number of lines.
783    ///
784    /// Clamps so that the last item can still appear at the top of the viewport.
785    pub fn scroll_down(&mut self, lines: usize, item_count: usize) {
786        self.offset = self
787            .offset
788            .saturating_add(lines)
789            .min(item_count.saturating_sub(1));
790    }
791
792    /// Move selection to the next item.
793    ///
794    /// If nothing is selected, selects the first item. Clamps to the last item.
795    pub fn select_next(&mut self, item_count: usize) {
796        if item_count == 0 {
797            return;
798        }
799        let next = match self.selected {
800            Some(i) => (i + 1).min(item_count.saturating_sub(1)),
801            None => 0,
802        };
803        self.selected = Some(next);
804        if !self.multi_select_enabled {
805            self.multi_selected.clear();
806            self.multi_selected.insert(next);
807        }
808        self.scroll_into_view_requested = true;
809        #[cfg(feature = "tracing")]
810        self.log_selection_change("select_next");
811    }
812
813    /// Move selection to the previous item.
814    ///
815    /// If nothing is selected, selects the first item. Clamps to 0.
816    pub fn select_previous(&mut self) {
817        let prev = match self.selected {
818            Some(i) => i.saturating_sub(1),
819            None => 0,
820        };
821        self.selected = Some(prev);
822        if !self.multi_select_enabled {
823            self.multi_selected.clear();
824            self.multi_selected.insert(prev);
825        }
826        self.scroll_into_view_requested = true;
827        #[cfg(feature = "tracing")]
828        self.log_selection_change("select_previous");
829    }
830}
831
832// ============================================================================
833// Stateful Persistence Implementation
834// ============================================================================
835
836/// Persistable state for a [`ListState`].
837///
838/// Contains the user-facing state that should survive sessions.
839#[derive(Clone, Debug, Default, PartialEq)]
840#[cfg_attr(
841    feature = "state-persistence",
842    derive(serde::Serialize, serde::Deserialize)
843)]
844pub struct ListPersistState {
845    /// Selected item index.
846    pub selected: Option<usize>,
847    /// Scroll offset (first visible item).
848    pub offset: usize,
849    /// Incremental filter query.
850    pub filter_query: String,
851    /// Whether multi-select mode was enabled.
852    pub multi_select_enabled: bool,
853    /// Multi-selected indices when multi-select mode is enabled.
854    pub multi_selected: Vec<usize>,
855}
856
857impl Stateful for ListState {
858    type State = ListPersistState;
859
860    fn state_key(&self) -> Option<StateKey> {
861        // No persistence_id, no identity: two unnamed lists must not share one.
862        self.persistence_id
863            .as_deref()
864            .map(|id| StateKey::new("List", id))
865    }
866
867    fn save_state(&self) -> ListPersistState {
868        ListPersistState {
869            selected: self.selected,
870            offset: self.offset,
871            filter_query: self.filter_query.clone(),
872            multi_select_enabled: self.multi_select_enabled,
873            multi_selected: self.multi_selected.iter().copied().collect(),
874        }
875    }
876
877    fn restore_state(&mut self, state: ListPersistState) {
878        self.selected = state.selected;
879        self.hovered = None;
880        self.offset = state.offset;
881        self.filter_query = state.filter_query;
882        self.multi_select_enabled = state.multi_select_enabled;
883        self.multi_selected = state.multi_selected.into_iter().collect();
884    }
885}
886
887impl<'a> StatefulWidget for List<'a> {
888    type State = ListState;
889
890    fn render(&self, area: Rect, frame: &mut Frame, state: &mut Self::State) {
891        #[cfg(feature = "tracing")]
892        let _widget_span = tracing::debug_span!(
893            "widget_render",
894            widget = "List",
895            x = area.x,
896            y = area.y,
897            w = area.width,
898            h = area.height
899        )
900        .entered();
901
902        #[cfg(feature = "tracing")]
903        let render_start = Instant::now();
904        #[cfg(feature = "tracing")]
905        let total_items = self.items.len();
906        let filter_active = !state.filter_query.trim().is_empty();
907        #[cfg(feature = "tracing")]
908        let selected_count = state.selected_count();
909        #[cfg(feature = "tracing")]
910        let render_span = tracing::debug_span!(
911            "list.render",
912            total_items,
913            visible_items = tracing::field::Empty,
914            selected_count,
915            filter_active,
916            render_duration_us = tracing::field::Empty
917        );
918        #[cfg(feature = "tracing")]
919        let _render_guard = render_span.enter();
920
921        let list_area = match &self.block {
922            Some(block) => {
923                let inner = block.inner(area);
924                crate::render_block_without_a11y(block, area, frame);
925                inner
926            }
927            None => area,
928        };
929
930        let mut rendered_visible_items = 0usize;
931
932        if !list_area.is_empty() {
933            // Clear the owned list area so shorter rows and empty states do not
934            // leak stale content from prior renders.
935            clear_text_area(frame, list_area, self.style);
936
937            if self.items.is_empty() {
938                state.selected = None;
939                state.hovered = None;
940                state.offset = 0;
941                state.multi_selected.clear();
942                self.push_stateful_accessibility(list_area, frame, state, &[]);
943                draw_text_span(
944                    frame,
945                    list_area.x,
946                    list_area.y,
947                    "No items",
948                    self.style,
949                    list_area.right(),
950                );
951            } else {
952                // Clamp selection/hover to item bounds before applying filters.
953                if let Some(selected) = state.selected
954                    && selected >= self.items.len()
955                {
956                    state.selected = Some(self.items.len().saturating_sub(1));
957                }
958                if let Some(hovered) = state.hovered
959                    && hovered >= self.items.len()
960                {
961                    state.hovered = None;
962                }
963
964                let filtered_indices = self.filtered_indices(state);
965                self.apply_filtered_selection_guard(state, &filtered_indices, filter_active);
966
967                if filtered_indices.is_empty() {
968                    self.push_stateful_accessibility(list_area, frame, state, &filtered_indices);
969                    draw_text_span(
970                        frame,
971                        list_area.x,
972                        list_area.y,
973                        "No matches",
974                        self.style,
975                        list_area.right(),
976                    );
977                } else {
978                    let list_height = list_area.height as usize;
979                    let max_offset = filtered_indices.len().saturating_sub(list_height.max(1));
980                    state.offset = state.offset.min(max_offset);
981
982                    if let Some(hovered) = state.hovered
983                        && filtered_indices.binary_search(&hovered).is_err()
984                    {
985                        state.hovered = None;
986                    }
987
988                    // Ensure visible range includes selected item.
989                    if state.scroll_into_view_requested {
990                        if let Some(selected) = state.selected
991                            && let Some(selected_pos) =
992                                filtered_indices.binary_search(&selected).ok()
993                        {
994                            if selected_pos >= state.offset + list_height {
995                                state.offset = selected_pos - list_height + 1;
996                            } else if selected_pos < state.offset {
997                                state.offset = selected_pos;
998                            }
999                        }
1000                        state.scroll_into_view_requested = false;
1001                    }
1002
1003                    self.push_stateful_accessibility(list_area, frame, state, &filtered_indices);
1004
1005                    for (row, item_index) in filtered_indices
1006                        .iter()
1007                        .skip(state.offset)
1008                        .take(list_height)
1009                        .enumerate()
1010                    {
1011                        let i = *item_index;
1012                        let item = &self.items[i];
1013                        let y = list_area.y.saturating_add(row as u16);
1014                        if y >= list_area.bottom() {
1015                            break;
1016                        }
1017                        let is_selected = state.selected == Some(i)
1018                            || (state.multi_select_enabled && state.multi_selected.contains(&i));
1019                        let is_hovered = state.hovered == Some(i);
1020
1021                        // Determine style: merge highlight on top of item style so
1022                        // unset highlight properties inherit from the item.
1023                        let mut item_style = if is_hovered {
1024                            self.hover_style.merge(&item.style)
1025                        } else {
1026                            item.style
1027                        };
1028                        if is_selected {
1029                            item_style = self.highlight_style.merge(&item_style);
1030                        }
1031
1032                        // Apply item background style to the whole row
1033                        let row_area = Rect::new(list_area.x, y, list_area.width, 1);
1034                        clear_text_row(frame, row_area, item_style);
1035
1036                        // Determine symbol
1037                        let symbol = if is_selected {
1038                            self.highlight_symbol.unwrap_or(item.marker)
1039                        } else {
1040                            item.marker
1041                        };
1042
1043                        let mut x = list_area.x;
1044
1045                        // Draw symbol if present
1046                        if !symbol.is_empty() {
1047                            x = draw_text_span(frame, x, y, symbol, item_style, list_area.right());
1048                            // Add a space after symbol
1049                            x = draw_text_span(frame, x, y, " ", item_style, list_area.right());
1050                        }
1051
1052                        // Draw content
1053                        // Note: List items are currently single-line for simplicity in v1
1054                        if let Some(line) = item.content.lines().first() {
1055                            for span in line.spans() {
1056                                let span_style = match span.style {
1057                                    Some(s) => s.merge(&item_style),
1058                                    None => item_style,
1059                                };
1060                                x = draw_text_span_with_link(
1061                                    frame,
1062                                    x,
1063                                    y,
1064                                    &span.content,
1065                                    span_style,
1066                                    list_area.right(),
1067                                    span.link.as_deref(),
1068                                );
1069                                if x >= list_area.right() {
1070                                    break;
1071                                }
1072                            }
1073                        }
1074
1075                        // Register hit region for this item (if hit testing enabled)
1076                        if let Some(id) = self.hit_id {
1077                            frame.register_hit(row_area, id, HitRegion::Content, i as u64);
1078                        }
1079
1080                        rendered_visible_items = rendered_visible_items.saturating_add(1);
1081                    }
1082
1083                    if filtered_indices.len() > list_height && list_area.width > 0 {
1084                        let indicator_x = list_area.right().saturating_sub(1);
1085                        if state.offset > 0 {
1086                            draw_text_span(
1087                                frame,
1088                                indicator_x,
1089                                list_area.y,
1090                                "↑",
1091                                self.style,
1092                                list_area.right(),
1093                            );
1094                        }
1095                        if state.offset + list_height < filtered_indices.len() {
1096                            draw_text_span(
1097                                frame,
1098                                indicator_x,
1099                                list_area.bottom().saturating_sub(1),
1100                                "↓",
1101                                self.style,
1102                                list_area.right(),
1103                            );
1104                        }
1105                    }
1106                }
1107            }
1108        }
1109
1110        #[cfg(feature = "tracing")]
1111        {
1112            let elapsed_us = render_start.elapsed().as_micros() as u64;
1113            render_span.record("visible_items", rendered_visible_items);
1114            render_span.record("render_duration_us", elapsed_us);
1115            tracing::debug!(
1116                message = "list.metrics",
1117                total_items,
1118                visible_items = rendered_visible_items,
1119                selected_count = state.selected_count(),
1120                filter_active,
1121                list_render_duration_us = elapsed_us
1122            );
1123        }
1124    }
1125}
1126
1127impl<'a> Widget for List<'a> {
1128    fn render(&self, area: Rect, frame: &mut Frame) {
1129        let mut state = ListState::default();
1130        StatefulWidget::render(self, area, frame, &mut state);
1131    }
1132}
1133
1134impl ftui_a11y::Accessible for List<'_> {
1135    fn accessibility_nodes(&self, area: Rect) -> Vec<ftui_a11y::node::A11yNodeInfo> {
1136        use ftui_a11y::node::{A11yNodeInfo, A11yRole};
1137
1138        let base_id = crate::a11y_node_id(area);
1139        let item_count = self.items.len();
1140        let child_ids: Vec<u64> = (0..item_count).map(|i| base_id + 1 + i as u64).collect();
1141
1142        let title = self
1143            .block
1144            .as_ref()
1145            .and_then(|b| b.title_text())
1146            .unwrap_or_default();
1147
1148        let mut list_node =
1149            A11yNodeInfo::new(base_id, A11yRole::List, area).with_children(child_ids);
1150        if !title.is_empty() {
1151            list_node = list_node.with_name(title);
1152        }
1153        list_node = list_node.with_description(format!("{item_count} items"));
1154
1155        let mut nodes = vec![list_node];
1156        for (i, item) in self.items.iter().enumerate() {
1157            let item_id = base_id + 1 + i as u64;
1158            let item_text = item
1159                .content
1160                .lines()
1161                .first()
1162                .map(|line| line.to_plain_text())
1163                .unwrap_or_default();
1164            let item_node =
1165                A11yNodeInfo::new(item_id, A11yRole::ListItem, area).with_parent(base_id);
1166            let item_node = if item_text.is_empty() {
1167                item_node
1168            } else {
1169                item_node.with_name(item_text)
1170            };
1171            nodes.push(item_node);
1172        }
1173        nodes
1174    }
1175}
1176
1177impl MeasurableWidget for ListItem<'_> {
1178    fn measure(&self, _available: Size) -> SizeConstraints {
1179        // ListItem is a single line of text with optional marker
1180        let marker_width = display_width(self.marker) as u16;
1181        let space_after_marker = if self.marker.is_empty() { 0u16 } else { 1 };
1182
1183        // Get text width from the first line (List currently renders only first line)
1184        let text_width = self
1185            .content
1186            .lines()
1187            .first()
1188            .map(|line| line.width())
1189            .unwrap_or(0)
1190            .min(u16::MAX as usize) as u16;
1191
1192        let total_width = marker_width
1193            .saturating_add(space_after_marker)
1194            .saturating_add(text_width);
1195
1196        // ListItem is always 1 line tall
1197        SizeConstraints::exact(Size::new(total_width, 1))
1198    }
1199
1200    fn has_intrinsic_size(&self) -> bool {
1201        true
1202    }
1203}
1204
1205impl MeasurableWidget for List<'_> {
1206    fn measure(&self, available: Size) -> SizeConstraints {
1207        // Get block chrome if present
1208        let (chrome_width, chrome_height) = self
1209            .block
1210            .as_ref()
1211            .map(|b| b.chrome_size())
1212            .unwrap_or((0, 0));
1213
1214        if self.items.is_empty() {
1215            // Empty list: just the chrome
1216            return SizeConstraints {
1217                min: Size::new(chrome_width, chrome_height),
1218                preferred: Size::new(chrome_width, chrome_height),
1219                max: None,
1220            };
1221        }
1222
1223        // Calculate inner available space
1224        let inner_available = Size::new(
1225            available.width.saturating_sub(chrome_width),
1226            available.height.saturating_sub(chrome_height),
1227        );
1228
1229        // Measure all items
1230        let mut max_width: u16 = 0;
1231        let mut total_height: u16 = 0;
1232
1233        for item in &self.items {
1234            let item_constraints = item.measure(inner_available);
1235            max_width = max_width.max(item_constraints.preferred.width);
1236            total_height = total_height.saturating_add(item_constraints.preferred.height);
1237        }
1238
1239        // Add highlight symbol width if present
1240        if let Some(symbol) = self.highlight_symbol {
1241            let symbol_width = display_width(symbol) as u16 + 1; // +1 for space
1242            max_width = max_width.saturating_add(symbol_width);
1243        }
1244
1245        // Add chrome
1246        let preferred_width = max_width.saturating_add(chrome_width);
1247        let preferred_height = total_height.saturating_add(chrome_height);
1248
1249        // Minimum is chrome + 1 item height (can scroll)
1250        let min_height = chrome_height.saturating_add(1.min(total_height));
1251
1252        SizeConstraints {
1253            min: Size::new(chrome_width, min_height),
1254            preferred: Size::new(preferred_width, preferred_height),
1255            max: None, // Lists can scroll, so no max
1256        }
1257    }
1258
1259    fn has_intrinsic_size(&self) -> bool {
1260        !self.items.is_empty()
1261    }
1262}
1263
1264// ============================================================================
1265// Undo Support Implementation
1266// ============================================================================
1267
1268/// Snapshot of ListState for undo.
1269#[derive(Debug, Clone)]
1270pub struct ListStateSnapshot {
1271    selected: Option<usize>,
1272    offset: usize,
1273    filter_query: String,
1274    multi_select_enabled: bool,
1275    multi_selected: Vec<usize>,
1276}
1277
1278impl UndoSupport for ListState {
1279    fn undo_widget_id(&self) -> UndoWidgetId {
1280        self.undo_id
1281    }
1282
1283    fn create_snapshot(&self) -> Box<dyn std::any::Any + Send> {
1284        Box::new(ListStateSnapshot {
1285            selected: self.selected,
1286            offset: self.offset,
1287            filter_query: self.filter_query.clone(),
1288            multi_select_enabled: self.multi_select_enabled,
1289            multi_selected: self.multi_selected.iter().copied().collect(),
1290        })
1291    }
1292
1293    fn restore_snapshot(&mut self, snapshot: &dyn std::any::Any) -> bool {
1294        if let Some(snap) = snapshot.downcast_ref::<ListStateSnapshot>() {
1295            self.selected = snap.selected;
1296            self.hovered = None;
1297            self.offset = snap.offset;
1298            self.filter_query = snap.filter_query.clone();
1299            self.multi_select_enabled = snap.multi_select_enabled;
1300            self.multi_selected = snap.multi_selected.iter().copied().collect();
1301            true
1302        } else {
1303            false
1304        }
1305    }
1306}
1307
1308impl ListUndoExt for ListState {
1309    fn selected_index(&self) -> Option<usize> {
1310        self.selected
1311    }
1312
1313    fn set_selected_index(&mut self, index: Option<usize>) {
1314        self.selected = index;
1315        if index.is_none() {
1316            self.offset = 0;
1317            self.multi_selected.clear();
1318        } else if !self.multi_select_enabled
1319            && let Some(selected) = index
1320        {
1321            self.multi_selected.clear();
1322            self.multi_selected.insert(selected);
1323        }
1324    }
1325}
1326
1327impl ListState {
1328    /// Get the undo widget ID.
1329    ///
1330    /// This can be used to associate undo commands with this state instance.
1331    #[must_use]
1332    pub fn undo_id(&self) -> UndoWidgetId {
1333        self.undo_id
1334    }
1335}
1336
1337#[cfg(test)]
1338mod tests {
1339    use super::*;
1340    use ftui_a11y::tree::{A11yTree, A11yTreeBuilder, AnnouncementReason, ScreenReaderPolicy};
1341    use ftui_core::event::{KeyCode, KeyEvent};
1342    use ftui_render::cell::Cell;
1343    use ftui_render::grapheme_pool::GraphemePool;
1344    #[cfg(feature = "tracing")]
1345    use std::sync::{Arc, Mutex};
1346    #[cfg(feature = "tracing")]
1347    use tracing::Subscriber;
1348    #[cfg(feature = "tracing")]
1349    use tracing_subscriber::Layer;
1350    #[cfg(feature = "tracing")]
1351    use tracing_subscriber::layer::{Context, SubscriberExt};
1352
1353    fn row_text(frame: &Frame, y: u16) -> String {
1354        let width = frame.buffer.width();
1355        let mut actual = String::new();
1356        for x in 0..width {
1357            let ch = frame
1358                .buffer
1359                .get(x, y)
1360                .and_then(|cell| cell.content.as_char())
1361                .unwrap_or(' ');
1362            actual.push(ch);
1363        }
1364        actual.trim().to_string()
1365    }
1366
1367    fn render_list_a11y(list: &List<'_>, state: &mut ListState, area: Rect) -> A11yTree {
1368        let mut builder = A11yTreeBuilder::new();
1369        {
1370            let mut pool = GraphemePool::new();
1371            let mut frame = Frame::new(80, 24, &mut pool);
1372            frame.set_a11y(&mut builder);
1373            StatefulWidget::render(list, area, &mut frame, state);
1374            frame.finish_a11y();
1375        }
1376        builder.build()
1377    }
1378
1379    #[test]
1380    fn stateful_list_accessibility_reflects_selection_focus_and_visible_rows() {
1381        let list = List::new(["Alpha", "Beta", "Gamma", "Delta"]).accessibility_id(7300);
1382        let mut state = ListState::default().with_focused(true);
1383        state.select(Some(2));
1384        let tree = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 2));
1385        assert_eq!(tree.root_id(), Some(7300));
1386        let root = tree.root().unwrap();
1387        assert_eq!(root.role, ftui_a11y::node::A11yRole::List);
1388        assert_eq!(root.children.len(), 2);
1389        assert_eq!(tree.focused().unwrap().name.as_deref(), Some("Gamma"));
1390        assert!(tree.focused().unwrap().state.selected);
1391        assert_eq!(state.offset, 1);
1392        assert_eq!(
1393            tree.node(root.children[0]).unwrap().name.as_deref(),
1394            Some("Beta")
1395        );
1396    }
1397
1398    #[test]
1399    fn stateful_list_selection_change_announces_once_only_when_focused() {
1400        let list = List::new(["Alpha", "Beta", "Gamma"]).accessibility_id(7301);
1401        let mut state = ListState::default().with_focused(true);
1402        state.select(Some(0));
1403        let before = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1404        state.select_next(3);
1405        let after = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1406        let batch = after.screen_reader_announcements_since(&before, ScreenReaderPolicy::default());
1407        assert_eq!(batch.announcements.len(), 1);
1408        assert_eq!(batch.dropped_count, 0);
1409        assert_eq!(
1410            batch.announcements[0].reason,
1411            AnnouncementReason::FocusChanged
1412        );
1413        assert!(batch.announcements[0].text.contains("Beta"));
1414
1415        state.set_focused(false);
1416        let unfocused = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1417        state.select_next(3);
1418        let moved = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1419        assert!(moved.focused().is_none());
1420        assert!(
1421            moved
1422                .screen_reader_announcements_since(&unfocused, ScreenReaderPolicy::default())
1423                .announcements
1424                .is_empty()
1425        );
1426    }
1427
1428    #[test]
1429    fn stateful_list_filter_semantics_match_visible_filtered_items_without_query_chatter() {
1430        let list = List::new(["apple", "apricot", "banana", "berry"]).accessibility_id(7302);
1431        let mut state = ListState::default().with_focused(true);
1432        state.select(Some(0));
1433        let before = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1434        state.set_filter_query("ap");
1435        let filtered = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 3));
1436        let root = filtered.root().unwrap();
1437        assert_eq!(root.description.as_deref(), Some("2 matching items"));
1438        assert_eq!(root.children.len(), 2);
1439        assert_eq!(
1440            filtered.node(root.children[0]).unwrap().name.as_deref(),
1441            Some("apple")
1442        );
1443        assert_eq!(
1444            filtered.node(root.children[1]).unwrap().name.as_deref(),
1445            Some("apricot")
1446        );
1447        assert_eq!(filtered.focused_id(), before.focused_id());
1448        assert!(
1449            filtered
1450                .screen_reader_announcements_since(&before, ScreenReaderPolicy::default())
1451                .announcements
1452                .is_empty()
1453        );
1454    }
1455
1456    #[test]
1457    fn stateful_list_block_title_is_single_semantic_root_not_duplicate_group() {
1458        let list = List::new(["One", "Two"])
1459            .block(Block::bordered().title("Choices"))
1460            .accessibility_id(7303);
1461        let mut state = ListState::default();
1462        // Height 7, not 5: `Block::bordered()` is `borders(ALL)` *and*
1463        // `padding(Sides::all(1))`, so it insets two rows at each end. A
1464        // 5-row area leaves exactly one visible row, one item node, and a
1465        // `node_count` of 2 - which says nothing about whether the title
1466        // produced a duplicate Group, the thing this test is named for.
1467        let tree = render_list_a11y(&list, &mut state, Rect::new(0, 0, 30, 7));
1468        assert_eq!(tree.root_id(), Some(7303));
1469        assert_eq!(tree.root().unwrap().name.as_deref(), Some("Choices"));
1470        let inventory: Vec<_> = tree
1471            .nodes()
1472            .map(|n| (n.id, n.role, n.name.clone(), n.bounds))
1473            .collect();
1474        assert_eq!(
1475            tree.node_count(),
1476            3,
1477            "expected the list root and both items; tree was {inventory:#?}"
1478        );
1479        assert!(
1480            !tree
1481                .nodes()
1482                .any(|node| node.role == ftui_a11y::node::A11yRole::Group)
1483        );
1484    }
1485
1486    fn raw_row_text(frame: &Frame, y: u16) -> String {
1487        let width = frame.buffer.width();
1488        let mut actual = String::new();
1489        for x in 0..width {
1490            let ch = frame
1491                .buffer
1492                .get(x, y)
1493                .and_then(|cell| cell.content.as_char())
1494                .unwrap_or(' ');
1495            actual.push(ch);
1496        }
1497        actual
1498    }
1499
1500    #[cfg(feature = "tracing")]
1501    #[derive(Debug, Default)]
1502    struct ListTraceState {
1503        list_render_seen: bool,
1504        has_total_items_field: bool,
1505        has_visible_items_field: bool,
1506        has_selected_count_field: bool,
1507        has_filter_active_field: bool,
1508        render_duration_recorded: bool,
1509        selection_events: usize,
1510    }
1511
1512    #[cfg(feature = "tracing")]
1513    struct ListTraceCapture {
1514        state: Arc<Mutex<ListTraceState>>,
1515    }
1516
1517    #[cfg(feature = "tracing")]
1518    impl<S> Layer<S> for ListTraceCapture
1519    where
1520        S: Subscriber + for<'lookup> tracing_subscriber::registry::LookupSpan<'lookup>,
1521    {
1522        fn on_new_span(
1523            &self,
1524            attrs: &tracing::span::Attributes<'_>,
1525            _id: &tracing::Id,
1526            _ctx: Context<'_, S>,
1527        ) {
1528            if attrs.metadata().name() != "list.render" {
1529                return;
1530            }
1531            let fields = attrs.metadata().fields();
1532            let mut state = self.state.lock().expect("list trace state lock");
1533            state.list_render_seen = true;
1534            state.has_total_items_field |= fields.field("total_items").is_some();
1535            state.has_visible_items_field |= fields.field("visible_items").is_some();
1536            state.has_selected_count_field |= fields.field("selected_count").is_some();
1537            state.has_filter_active_field |= fields.field("filter_active").is_some();
1538        }
1539
1540        fn on_record(
1541            &self,
1542            id: &tracing::Id,
1543            values: &tracing::span::Record<'_>,
1544            ctx: Context<'_, S>,
1545        ) {
1546            let Some(span) = ctx.span(id) else {
1547                return;
1548            };
1549            if span.metadata().name() != "list.render" {
1550                return;
1551            }
1552            struct DurationVisitor {
1553                saw_duration: bool,
1554            }
1555            impl tracing::field::Visit for DurationVisitor {
1556                fn record_u64(&mut self, field: &tracing::field::Field, _value: u64) {
1557                    if field.name() == "render_duration_us" {
1558                        self.saw_duration = true;
1559                    }
1560                }
1561
1562                fn record_debug(
1563                    &mut self,
1564                    field: &tracing::field::Field,
1565                    _value: &dyn std::fmt::Debug,
1566                ) {
1567                    if field.name() == "render_duration_us" {
1568                        self.saw_duration = true;
1569                    }
1570                }
1571            }
1572            let mut visitor = DurationVisitor {
1573                saw_duration: false,
1574            };
1575            values.record(&mut visitor);
1576            if visitor.saw_duration {
1577                self.state
1578                    .lock()
1579                    .expect("list trace state lock")
1580                    .render_duration_recorded = true;
1581            }
1582        }
1583
1584        fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1585            struct MessageVisitor {
1586                message: Option<String>,
1587            }
1588            impl tracing::field::Visit for MessageVisitor {
1589                fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
1590                    if field.name() == "message" {
1591                        self.message = Some(value.to_owned());
1592                    }
1593                }
1594
1595                fn record_debug(
1596                    &mut self,
1597                    field: &tracing::field::Field,
1598                    value: &dyn std::fmt::Debug,
1599                ) {
1600                    if field.name() == "message" {
1601                        self.message = Some(format!("{value:?}").trim_matches('"').to_owned());
1602                    }
1603                }
1604            }
1605            let mut visitor = MessageVisitor { message: None };
1606            event.record(&mut visitor);
1607            if visitor.message.as_deref() == Some("list.selection") {
1608                let mut state = self.state.lock().expect("list trace state lock");
1609                state.selection_events = state.selection_events.saturating_add(1);
1610            }
1611        }
1612    }
1613
1614    #[test]
1615    fn render_empty_list() {
1616        let list = List::new(Vec::<ListItem>::new());
1617        let area = Rect::new(0, 0, 10, 5);
1618        let mut pool = GraphemePool::new();
1619        let mut frame = Frame::new(10, 5, &mut pool);
1620        Widget::render(&list, area, &mut frame);
1621    }
1622
1623    #[test]
1624    fn render_simple_list() {
1625        let items = vec![
1626            ListItem::new("Item A"),
1627            ListItem::new("Item B"),
1628            ListItem::new("Item C"),
1629        ];
1630        let list = List::new(items);
1631        let area = Rect::new(0, 0, 10, 3);
1632        let mut pool = GraphemePool::new();
1633        let mut frame = Frame::new(10, 3, &mut pool);
1634        let mut state = ListState::default();
1635        StatefulWidget::render(&list, area, &mut frame, &mut state);
1636
1637        assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('I'));
1638        assert_eq!(frame.buffer.get(5, 0).unwrap().content.as_char(), Some('A'));
1639        assert_eq!(frame.buffer.get(5, 1).unwrap().content.as_char(), Some('B'));
1640        assert_eq!(frame.buffer.get(5, 2).unwrap().content.as_char(), Some('C'));
1641    }
1642
1643    #[test]
1644    fn list_state_select() {
1645        let mut state = ListState::default();
1646        assert_eq!(state.selected(), None);
1647
1648        state.select(Some(2));
1649        assert_eq!(state.selected(), Some(2));
1650
1651        state.select(None);
1652        assert_eq!(state.selected(), None);
1653        assert_eq!(state.offset, 0);
1654    }
1655
1656    #[test]
1657    fn list_scrolls_to_selected() {
1658        let items: Vec<ListItem> = (0..10)
1659            .map(|i| ListItem::new(format!("Item {i}")))
1660            .collect();
1661        let list = List::new(items);
1662        let area = Rect::new(0, 0, 10, 3);
1663        let mut pool = GraphemePool::new();
1664        let mut frame = Frame::new(10, 3, &mut pool);
1665        let mut state = ListState::default();
1666        state.select(Some(5));
1667
1668        StatefulWidget::render(&list, area, &mut frame, &mut state);
1669        // offset should have been adjusted so item 5 is visible
1670        assert!(state.offset <= 5);
1671        assert!(state.offset + 3 > 5);
1672    }
1673
1674    #[test]
1675    fn list_clamps_selection() {
1676        let items = vec![ListItem::new("A"), ListItem::new("B")];
1677        let list = List::new(items);
1678        let area = Rect::new(0, 0, 10, 3);
1679        let mut pool = GraphemePool::new();
1680        let mut frame = Frame::new(10, 3, &mut pool);
1681        let mut state = ListState::default();
1682        state.select(Some(10)); // out of bounds
1683
1684        StatefulWidget::render(&list, area, &mut frame, &mut state);
1685        // should clamp to last item
1686        assert_eq!(state.selected(), Some(1));
1687    }
1688
1689    #[test]
1690    fn render_list_with_highlight_symbol() {
1691        let items = vec![ListItem::new("A"), ListItem::new("B")];
1692        let list = List::new(items).highlight_symbol(">");
1693        let area = Rect::new(0, 0, 10, 2);
1694        let mut pool = GraphemePool::new();
1695        let mut frame = Frame::new(10, 2, &mut pool);
1696        let mut state = ListState::default();
1697        state.select(Some(0));
1698
1699        StatefulWidget::render(&list, area, &mut frame, &mut state);
1700        // First item should have ">" symbol
1701        assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('>'));
1702    }
1703
1704    #[test]
1705    fn render_zero_area() {
1706        let list = List::new(vec![ListItem::new("A")]);
1707        let area = Rect::new(0, 0, 0, 0);
1708        let mut pool = GraphemePool::new();
1709        let mut frame = Frame::new(1, 1, &mut pool);
1710        let mut state = ListState::default();
1711        StatefulWidget::render(&list, area, &mut frame, &mut state);
1712    }
1713
1714    #[test]
1715    fn list_item_from_str() {
1716        let item: ListItem = "hello".into();
1717        assert_eq!(
1718            item.content.lines().first().unwrap().to_plain_text(),
1719            "hello"
1720        );
1721        assert_eq!(item.marker, "");
1722    }
1723
1724    #[test]
1725    fn list_item_with_marker() {
1726        let items = vec![
1727            ListItem::new("A").marker("•"),
1728            ListItem::new("B").marker("•"),
1729        ];
1730        let list = List::new(items);
1731        let area = Rect::new(0, 0, 10, 2);
1732        let mut pool = GraphemePool::new();
1733        let mut frame = Frame::new(10, 2, &mut pool);
1734        let mut state = ListState::default();
1735        StatefulWidget::render(&list, area, &mut frame, &mut state);
1736
1737        // Marker should be rendered at the start
1738        assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('•'));
1739        assert_eq!(frame.buffer.get(0, 1).unwrap().content.as_char(), Some('•'));
1740    }
1741
1742    #[test]
1743    fn list_state_deselect_resets_offset() {
1744        let mut state = ListState {
1745            offset: 5,
1746            ..Default::default()
1747        };
1748        state.select(Some(10));
1749        assert_eq!(state.offset, 5); // select doesn't reset offset
1750
1751        state.select(None);
1752        assert_eq!(state.offset, 0); // deselect resets offset
1753    }
1754
1755    #[test]
1756    fn list_scrolls_up_when_selection_above_viewport() {
1757        let items: Vec<ListItem> = (0..10)
1758            .map(|i| ListItem::new(format!("Item {i}")))
1759            .collect();
1760        let list = List::new(items);
1761        let area = Rect::new(0, 0, 10, 3);
1762        let mut pool = GraphemePool::new();
1763        let mut frame = Frame::new(10, 3, &mut pool);
1764        let mut state = ListState::default();
1765
1766        // First scroll down
1767        state.select(Some(8));
1768        StatefulWidget::render(&list, area, &mut frame, &mut state);
1769        assert!(state.offset > 0);
1770
1771        // Now select item 0 - should scroll back up
1772        state.select(Some(0));
1773        StatefulWidget::render(&list, area, &mut frame, &mut state);
1774        assert_eq!(state.offset, 0);
1775    }
1776
1777    #[test]
1778    fn list_clamps_offset_to_fill_viewport_on_resize() {
1779        let items: Vec<ListItem> = (0..10)
1780            .map(|i| ListItem::new(format!("Item {i}")))
1781            .collect();
1782        let list = List::new(items);
1783
1784        let mut pool = GraphemePool::new();
1785        let mut state = ListState {
1786            offset: 7,
1787            ..Default::default()
1788        };
1789
1790        // Small viewport: show 7, 8, 9.
1791        let area_small = Rect::new(0, 0, 10, 3);
1792        let mut frame_small = Frame::new(10, 3, &mut pool);
1793        StatefulWidget::render(&list, area_small, &mut frame_small, &mut state);
1794        assert_eq!(state.offset, 7);
1795        assert!(row_text(&frame_small, 0).starts_with("Item 7"));
1796        assert!(row_text(&frame_small, 2).starts_with("Item 9"));
1797
1798        // Larger viewport: offset should pull back to fill the viewport (5..9).
1799        let area_large = Rect::new(0, 0, 10, 5);
1800        let mut frame_large = Frame::new(10, 5, &mut pool);
1801        StatefulWidget::render(&list, area_large, &mut frame_large, &mut state);
1802        assert_eq!(state.offset, 5);
1803        assert!(row_text(&frame_large, 0).starts_with("Item 5"));
1804        assert!(row_text(&frame_large, 4).starts_with("Item 9"));
1805    }
1806
1807    #[test]
1808    fn render_list_more_items_than_viewport() {
1809        let items: Vec<ListItem> = (0..20).map(|i| ListItem::new(format!("{i}"))).collect();
1810        let list = List::new(items);
1811        let area = Rect::new(0, 0, 5, 3);
1812        let mut pool = GraphemePool::new();
1813        let mut frame = Frame::new(5, 3, &mut pool);
1814        let mut state = ListState::default();
1815        StatefulWidget::render(&list, area, &mut frame, &mut state);
1816
1817        // Only first 3 should render
1818        assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('0'));
1819        assert_eq!(frame.buffer.get(0, 1).unwrap().content.as_char(), Some('1'));
1820        assert_eq!(frame.buffer.get(0, 2).unwrap().content.as_char(), Some('2'));
1821    }
1822
1823    #[test]
1824    fn widget_render_uses_default_state() {
1825        let items = vec![ListItem::new("X")];
1826        let list = List::new(items);
1827        let area = Rect::new(0, 0, 5, 1);
1828        let mut pool = GraphemePool::new();
1829        let mut frame = Frame::new(5, 1, &mut pool);
1830        // Using Widget trait (not StatefulWidget)
1831        Widget::render(&list, area, &mut frame);
1832        assert_eq!(frame.buffer.get(0, 0).unwrap().content.as_char(), Some('X'));
1833    }
1834
1835    #[test]
1836    fn list_registers_hit_regions() {
1837        let items = vec![ListItem::new("A"), ListItem::new("B"), ListItem::new("C")];
1838        let list = List::new(items).hit_id(HitId::new(42));
1839        let area = Rect::new(0, 0, 10, 3);
1840        let mut pool = GraphemePool::new();
1841        let mut frame = Frame::with_hit_grid(10, 3, &mut pool);
1842        let mut state = ListState::default();
1843        StatefulWidget::render(&list, area, &mut frame, &mut state);
1844
1845        // Each row should have a hit region with the item index as data
1846        let hit0 = frame.hit_test(5, 0);
1847        let hit1 = frame.hit_test(5, 1);
1848        let hit2 = frame.hit_test(5, 2);
1849
1850        assert_eq!(hit0, Some((HitId::new(42), HitRegion::Content, 0)));
1851        assert_eq!(hit1, Some((HitId::new(42), HitRegion::Content, 1)));
1852        assert_eq!(hit2, Some((HitId::new(42), HitRegion::Content, 2)));
1853    }
1854
1855    #[test]
1856    fn list_no_hit_without_hit_id() {
1857        let items = vec![ListItem::new("A")];
1858        let list = List::new(items); // No hit_id set
1859        let area = Rect::new(0, 0, 10, 1);
1860        let mut pool = GraphemePool::new();
1861        let mut frame = Frame::with_hit_grid(10, 1, &mut pool);
1862        let mut state = ListState::default();
1863        StatefulWidget::render(&list, area, &mut frame, &mut state);
1864
1865        // No hit region should be registered
1866        assert!(frame.hit_test(5, 0).is_none());
1867    }
1868
1869    #[test]
1870    fn list_no_hit_without_hit_grid() {
1871        let items = vec![ListItem::new("A")];
1872        let list = List::new(items).hit_id(HitId::new(1));
1873        let area = Rect::new(0, 0, 10, 1);
1874        let mut pool = GraphemePool::new();
1875        let mut frame = Frame::new(10, 1, &mut pool); // No hit grid
1876        let mut state = ListState::default();
1877        StatefulWidget::render(&list, area, &mut frame, &mut state);
1878
1879        // hit_test returns None when no hit grid
1880        assert!(frame.hit_test(5, 0).is_none());
1881    }
1882
1883    // --- MeasurableWidget tests ---
1884
1885    use crate::MeasurableWidget;
1886    use ftui_core::geometry::Size;
1887
1888    #[test]
1889    fn list_item_measure_simple() {
1890        let item = ListItem::new("Hello"); // 5 chars
1891        let constraints = item.measure(Size::MAX);
1892
1893        assert_eq!(constraints.preferred, Size::new(5, 1));
1894        assert_eq!(constraints.min, Size::new(5, 1));
1895        assert_eq!(constraints.max, Some(Size::new(5, 1)));
1896    }
1897
1898    #[test]
1899    fn list_item_measure_with_marker() {
1900        let item = ListItem::new("Hi").marker("•"); // • + space + Hi = 1 + 1 + 2 = 4
1901        let constraints = item.measure(Size::MAX);
1902
1903        assert_eq!(constraints.preferred.width, 4);
1904        assert_eq!(constraints.preferred.height, 1);
1905    }
1906
1907    #[test]
1908    fn list_item_has_intrinsic_size() {
1909        let item = ListItem::new("test");
1910        assert!(item.has_intrinsic_size());
1911    }
1912
1913    #[test]
1914    fn list_measure_empty() {
1915        let list = List::new(Vec::<ListItem>::new());
1916        let constraints = list.measure(Size::MAX);
1917
1918        assert_eq!(constraints.preferred, Size::new(0, 0));
1919        assert!(!list.has_intrinsic_size());
1920    }
1921
1922    #[test]
1923    fn list_measure_single_item() {
1924        let items = vec![ListItem::new("Hello")]; // 5 chars, 1 line
1925        let list = List::new(items);
1926        let constraints = list.measure(Size::MAX);
1927
1928        assert_eq!(constraints.preferred, Size::new(5, 1));
1929        assert_eq!(constraints.min.height, 1);
1930    }
1931
1932    #[test]
1933    fn list_measure_multiple_items() {
1934        let items = vec![
1935            ListItem::new("Short"),      // 5 chars
1936            ListItem::new("LongerItem"), // 10 chars
1937            ListItem::new("Tiny"),       // 4 chars
1938        ];
1939        let list = List::new(items);
1940        let constraints = list.measure(Size::MAX);
1941
1942        // Width is max of all items = 10
1943        assert_eq!(constraints.preferred.width, 10);
1944        // Height is sum of all items = 3
1945        assert_eq!(constraints.preferred.height, 3);
1946    }
1947
1948    #[test]
1949    fn list_measure_with_block() {
1950        let block = crate::block::Block::bordered(); // 4x4 chrome (borders + padding)
1951        let items = vec![ListItem::new("Hi")]; // 2 chars, 1 line
1952        let list = List::new(items).block(block);
1953        let constraints = list.measure(Size::MAX);
1954
1955        // 2 (text) + 4 (chrome) = 6 width
1956        // 1 (line) + 4 (chrome) = 5 height
1957        assert_eq!(constraints.preferred, Size::new(6, 5));
1958    }
1959
1960    #[test]
1961    fn list_measure_with_highlight_symbol() {
1962        let items = vec![ListItem::new("Item")]; // 4 chars
1963        let list = List::new(items).highlight_symbol(">"); // 1 char + space = 2
1964
1965        let constraints = list.measure(Size::MAX);
1966
1967        // 4 (text) + 2 (symbol + space) = 6
1968        assert_eq!(constraints.preferred.width, 6);
1969    }
1970
1971    #[test]
1972    fn list_has_intrinsic_size() {
1973        let items = vec![ListItem::new("X")];
1974        let list = List::new(items);
1975        assert!(list.has_intrinsic_size());
1976    }
1977
1978    #[test]
1979    fn list_min_height_is_one_row() {
1980        let items: Vec<ListItem> = (0..100)
1981            .map(|i| ListItem::new(format!("Item {i}")))
1982            .collect();
1983        let list = List::new(items);
1984        let constraints = list.measure(Size::MAX);
1985
1986        // Min height should be 1 (can scroll to see rest)
1987        assert_eq!(constraints.min.height, 1);
1988        // Preferred height is all items
1989        assert_eq!(constraints.preferred.height, 100);
1990    }
1991
1992    #[test]
1993    fn list_measure_is_pure() {
1994        let items = vec![ListItem::new("Test")];
1995        let list = List::new(items);
1996        let a = list.measure(Size::new(100, 50));
1997        let b = list.measure(Size::new(100, 50));
1998        assert_eq!(a, b);
1999    }
2000
2001    // --- Undo Support tests ---
2002
2003    #[test]
2004    fn list_state_undo_id_is_stable() {
2005        let state = ListState::default();
2006        let id1 = state.undo_id();
2007        let id2 = state.undo_id();
2008        assert_eq!(id1, id2);
2009    }
2010
2011    #[test]
2012    fn list_state_undo_id_unique_per_instance() {
2013        let state1 = ListState::default();
2014        let state2 = ListState::default();
2015        assert_ne!(state1.undo_id(), state2.undo_id());
2016    }
2017
2018    #[test]
2019    fn list_state_snapshot_and_restore() {
2020        let mut state = ListState::default();
2021        state.select(Some(5));
2022        state.offset = 3;
2023
2024        let snapshot = state.create_snapshot();
2025
2026        // Modify state
2027        state.select(Some(10));
2028        state.offset = 8;
2029        assert_eq!(state.selected(), Some(10));
2030        assert_eq!(state.offset, 8);
2031
2032        // Restore
2033        assert!(state.restore_snapshot(snapshot.as_ref()));
2034        assert_eq!(state.selected(), Some(5));
2035        assert_eq!(state.offset, 3);
2036    }
2037
2038    #[test]
2039    fn list_state_undo_ext_methods() {
2040        let mut state = ListState::default();
2041        assert_eq!(state.selected_index(), None);
2042
2043        state.set_selected_index(Some(3));
2044        assert_eq!(state.selected_index(), Some(3));
2045
2046        state.set_selected_index(None);
2047        assert_eq!(state.selected_index(), None);
2048        assert_eq!(state.offset, 0); // reset on deselect
2049    }
2050
2051    // --- Stateful Persistence tests ---
2052
2053    use crate::stateful::Stateful;
2054
2055    #[test]
2056    fn list_state_with_persistence_id() {
2057        let state = ListState::default().with_persistence_id("sidebar-menu");
2058        assert_eq!(state.persistence_id(), Some("sidebar-menu"));
2059    }
2060
2061    #[test]
2062    fn list_state_default_no_persistence_id() {
2063        let state = ListState::default();
2064        assert_eq!(state.persistence_id(), None);
2065    }
2066
2067    #[test]
2068    fn list_state_save_restore_round_trip() {
2069        let mut state = ListState::default().with_persistence_id("test");
2070        state.select(Some(7));
2071        state.offset = 4;
2072
2073        let saved = state.save_state();
2074        assert_eq!(saved.selected, Some(7));
2075        assert_eq!(saved.offset, 4);
2076
2077        // Reset state
2078        state.select(None);
2079        assert_eq!(state.selected, None);
2080        assert_eq!(state.offset, 0);
2081
2082        // Restore
2083        state.restore_state(saved);
2084        assert_eq!(state.selected, Some(7));
2085        assert_eq!(state.offset, 4);
2086    }
2087
2088    #[test]
2089    fn list_state_key_uses_persistence_id() {
2090        let state = ListState::default().with_persistence_id("file-browser");
2091        let key = state.state_key().expect("named list has a key");
2092        assert_eq!(key.widget_type, "List");
2093        assert_eq!(key.instance_id, "file-browser");
2094    }
2095
2096    #[test]
2097    fn list_state_without_id_is_not_persisted() {
2098        // bd-2fonp: every unnamed list used to key as ("List", "default"), so
2099        // a registry restored all of them to one state.
2100        assert!(ListState::default().state_key().is_none());
2101    }
2102
2103    #[test]
2104    fn list_persist_state_default() {
2105        let persist = ListPersistState::default();
2106        assert_eq!(persist.selected, None);
2107        assert_eq!(persist.offset, 0);
2108    }
2109
2110    // --- Mouse handling tests ---
2111
2112    use crate::mouse::MouseResult;
2113    use ftui_core::event::{MouseButton, MouseEvent, MouseEventKind};
2114
2115    #[test]
2116    fn list_state_click_selects() {
2117        let mut state = ListState::default();
2118        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2119        let hit = Some((HitId::new(1), HitRegion::Content, 3u64));
2120        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2121        assert_eq!(result, MouseResult::Selected(3));
2122        assert_eq!(state.selected(), Some(3));
2123    }
2124
2125    #[test]
2126    fn list_state_click_wrong_id_ignored() {
2127        let mut state = ListState::default();
2128        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2129        let hit = Some((HitId::new(99), HitRegion::Content, 3u64));
2130        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2131        assert_eq!(result, MouseResult::Ignored);
2132        assert_eq!(state.selected(), None);
2133    }
2134
2135    #[test]
2136    fn list_state_click_out_of_range() {
2137        let mut state = ListState::default();
2138        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2139        let hit = Some((HitId::new(1), HitRegion::Content, 15u64));
2140        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2141        assert_eq!(result, MouseResult::Ignored);
2142        assert_eq!(state.selected(), None);
2143    }
2144
2145    #[test]
2146    fn list_state_click_no_hit_ignored() {
2147        let mut state = ListState::default();
2148        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2149        let result = state.handle_mouse(&event, None, HitId::new(1), 10);
2150        assert_eq!(result, MouseResult::Ignored);
2151    }
2152
2153    #[test]
2154    #[allow(clippy::field_reassign_with_default)]
2155    fn list_state_scroll_up() {
2156        let mut state = {
2157            let mut s = ListState::default();
2158            s.offset = 10;
2159            s
2160        };
2161        state.scroll_up(3);
2162        assert_eq!(state.offset, 7);
2163    }
2164
2165    #[test]
2166    #[allow(clippy::field_reassign_with_default)]
2167    fn list_state_scroll_up_clamps_to_zero() {
2168        let mut state = {
2169            let mut s = ListState::default();
2170            s.offset = 1;
2171            s
2172        };
2173        state.scroll_up(5);
2174        assert_eq!(state.offset, 0);
2175    }
2176
2177    #[test]
2178    fn list_state_scroll_down() {
2179        let mut state = ListState::default();
2180        state.scroll_down(3, 20);
2181        assert_eq!(state.offset, 3);
2182    }
2183
2184    #[test]
2185    #[allow(clippy::field_reassign_with_default)]
2186    fn list_state_scroll_down_clamps() {
2187        let mut state = ListState::default();
2188        state.offset = 18;
2189        state.scroll_down(5, 20);
2190        assert_eq!(state.offset, 19); // item_count - 1
2191    }
2192
2193    #[test]
2194    #[allow(clippy::field_reassign_with_default)]
2195    fn list_state_scroll_wheel_up() {
2196        let mut state = {
2197            let mut s = ListState::default();
2198            s.offset = 10;
2199            s
2200        };
2201        let event = MouseEvent::new(MouseEventKind::ScrollUp, 0, 0);
2202        let result = state.handle_mouse(&event, None, HitId::new(1), 20);
2203        assert_eq!(result, MouseResult::Scrolled);
2204        assert_eq!(state.offset, 7);
2205    }
2206
2207    #[test]
2208    fn list_state_scroll_wheel_down() {
2209        let mut state = ListState::default();
2210        let event = MouseEvent::new(MouseEventKind::ScrollDown, 0, 0);
2211        let result = state.handle_mouse(&event, None, HitId::new(1), 20);
2212        assert_eq!(result, MouseResult::Scrolled);
2213        assert_eq!(state.offset, 3);
2214    }
2215
2216    #[test]
2217    fn list_state_select_next() {
2218        let mut state = ListState::default();
2219        state.select_next(5);
2220        assert_eq!(state.selected(), Some(0));
2221        state.select_next(5);
2222        assert_eq!(state.selected(), Some(1));
2223    }
2224
2225    #[test]
2226    fn list_state_select_next_clamps() {
2227        let mut state = ListState::default();
2228        state.select(Some(4));
2229        state.select_next(5);
2230        assert_eq!(state.selected(), Some(4)); // already at last
2231    }
2232
2233    #[test]
2234    fn list_state_select_next_empty() {
2235        let mut state = ListState::default();
2236        state.select_next(0);
2237        assert_eq!(state.selected(), None); // no items, no change
2238    }
2239
2240    #[test]
2241    fn list_state_select_previous() {
2242        let mut state = ListState::default();
2243        state.select(Some(3));
2244        state.select_previous();
2245        assert_eq!(state.selected(), Some(2));
2246    }
2247
2248    #[test]
2249    fn list_state_select_previous_clamps() {
2250        let mut state = ListState::default();
2251        state.select(Some(0));
2252        state.select_previous();
2253        assert_eq!(state.selected(), Some(0)); // already at first
2254    }
2255
2256    #[test]
2257    fn list_state_select_previous_from_none() {
2258        let mut state = ListState::default();
2259        state.select_previous();
2260        assert_eq!(state.selected(), Some(0));
2261    }
2262
2263    #[test]
2264    fn list_handle_key_down_from_none_selects_first() {
2265        let list = List::new(vec![
2266            ListItem::new("a"),
2267            ListItem::new("b"),
2268            ListItem::new("c"),
2269        ]);
2270        let mut state = ListState::default();
2271        assert_eq!(state.selected(), None);
2272
2273        // Press Down
2274        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2275        // Should select "a" (index 0)
2276        assert_eq!(state.selected(), Some(0));
2277    }
2278
2279    #[test]
2280    fn list_handle_key_up_from_none_selects_last() {
2281        let list = List::new(vec![
2282            ListItem::new("a"),
2283            ListItem::new("b"),
2284            ListItem::new("c"),
2285        ]);
2286        let mut state = ListState::default();
2287        assert_eq!(state.selected(), None);
2288
2289        // Press Up
2290        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2291        // Should select "c" (index 2)
2292        assert_eq!(state.selected(), Some(2));
2293    }
2294
2295    #[test]
2296    fn list_handle_key_ignores_key_release() {
2297        // With release events reported, "a" filtered for "aa" and each
2298        // arrow moved two rows.
2299        let list = List::new(vec![
2300            ListItem::new("alpha"),
2301            ListItem::new("beta"),
2302            ListItem::new("gamma"),
2303        ]);
2304        let mut state = ListState::default();
2305        for code in [KeyCode::Down, KeyCode::Down, KeyCode::Char('a')] {
2306            let press = KeyEvent::new(code);
2307            assert!(list.handle_key(&mut state, &press));
2308            assert!(!list.handle_key(&mut state, &press.with_kind(KeyEventKind::Release)));
2309        }
2310        assert_eq!(state.filter_query, "a");
2311    }
2312
2313    #[test]
2314    fn list_handle_key_navigation_supports_jk_and_arrows() {
2315        let list = List::new(vec![
2316            ListItem::new("a"),
2317            ListItem::new("b"),
2318            ListItem::new("c"),
2319        ]);
2320        let mut state = ListState::default();
2321        state.select(Some(0));
2322
2323        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2324        assert_eq!(state.selected(), Some(1));
2325        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2326        assert_eq!(state.selected(), Some(2));
2327        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2328        assert_eq!(state.selected(), Some(1));
2329        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('k'))));
2330        assert_eq!(state.selected(), Some(0));
2331    }
2332
2333    #[test]
2334    fn list_handle_key_filter_is_incremental_and_editable() {
2335        let list = List::new(vec![
2336            ListItem::new("alpha"),
2337            ListItem::new("banana"),
2338            ListItem::new("beta"),
2339        ]);
2340        let mut state = ListState::default();
2341
2342        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2343        assert_eq!(state.filter_query(), "b");
2344        assert_eq!(state.selected(), Some(1));
2345
2346        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('e'))));
2347        assert_eq!(state.filter_query(), "be");
2348        assert_eq!(state.selected(), Some(2));
2349
2350        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Backspace)));
2351        assert_eq!(state.filter_query(), "b");
2352
2353        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Escape)));
2354        assert_eq!(state.filter_query(), "");
2355    }
2356
2357    #[test]
2358    fn list_render_filter_no_matches_shows_empty_state() {
2359        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2360        let mut state = ListState::default();
2361        state.set_filter_query("zzz");
2362
2363        let mut pool = GraphemePool::new();
2364        let mut frame = Frame::new(14, 3, &mut pool);
2365        StatefulWidget::render(&list, Rect::new(0, 0, 14, 3), &mut frame, &mut state);
2366
2367        assert_eq!(row_text(&frame, 0), "No matches");
2368    }
2369
2370    #[test]
2371    fn list_render_shorter_item_clears_stale_row_suffix() {
2372        let mut pool = GraphemePool::new();
2373        let mut frame = Frame::new(12, 2, &mut pool);
2374        let mut state = ListState::default();
2375        let area = Rect::new(0, 0, 12, 2);
2376
2377        let long = List::new(vec![ListItem::new("alphabet")]);
2378        StatefulWidget::render(&long, area, &mut frame, &mut state);
2379
2380        let short = List::new(vec![ListItem::new("a")]);
2381        StatefulWidget::render(&short, area, &mut frame, &mut state);
2382
2383        assert_eq!(raw_row_text(&frame, 0), "a           ");
2384    }
2385
2386    #[test]
2387    fn list_render_empty_state_clears_stale_rows_and_tail() {
2388        let list = List::new(Vec::<ListItem>::new());
2389        let mut pool = GraphemePool::new();
2390        let mut frame = Frame::new(12, 3, &mut pool);
2391        let area = Rect::new(0, 0, 12, 3);
2392        frame.buffer.fill(area, Cell::from_char('X'));
2393
2394        Widget::render(&list, area, &mut frame);
2395
2396        assert_eq!(raw_row_text(&frame, 0), "No items    ");
2397        assert_eq!(raw_row_text(&frame, 1), "            ");
2398        assert_eq!(raw_row_text(&frame, 2), "            ");
2399    }
2400
2401    #[test]
2402    fn list_render_no_matches_clears_stale_rows_and_tail() {
2403        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2404        let mut state = ListState::default();
2405        state.set_filter_query("zzz");
2406
2407        let mut pool = GraphemePool::new();
2408        let mut frame = Frame::new(12, 3, &mut pool);
2409        let area = Rect::new(0, 0, 12, 3);
2410        frame.buffer.fill(area, Cell::from_char('X'));
2411
2412        StatefulWidget::render(&list, area, &mut frame, &mut state);
2413
2414        assert_eq!(raw_row_text(&frame, 0), "No matches  ");
2415        assert_eq!(raw_row_text(&frame, 1), "            ");
2416        assert_eq!(raw_row_text(&frame, 2), "            ");
2417    }
2418
2419    #[test]
2420    fn list_multi_select_toggle_with_space() {
2421        let list = List::new(vec![
2422            ListItem::new("alpha"),
2423            ListItem::new("beta"),
2424            ListItem::new("gamma"),
2425        ]);
2426        let mut state = ListState::default();
2427        state.set_multi_select(true);
2428        state.select(Some(0));
2429
2430        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2431        assert!(state.selected_indices().contains(&0));
2432
2433        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2434        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2435        assert!(state.selected_indices().contains(&1));
2436        assert_eq!(state.selected_count(), 2);
2437    }
2438
2439    #[test]
2440    fn list_render_draws_scroll_indicators() {
2441        let items: Vec<ListItem> = (0..8).map(|i| ListItem::new(format!("Item {i}"))).collect();
2442        let list = List::new(items);
2443        let mut state = ListState {
2444            selected: Some(4),
2445            offset: 2,
2446            scroll_into_view_requested: false,
2447            ..Default::default()
2448        };
2449        let mut pool = GraphemePool::new();
2450        let mut frame = Frame::new(8, 3, &mut pool);
2451        StatefulWidget::render(&list, Rect::new(0, 0, 8, 3), &mut frame, &mut state);
2452
2453        assert_eq!(
2454            frame.buffer.get(7, 0).and_then(|c| c.content.as_char()),
2455            Some('↑')
2456        );
2457        assert_eq!(
2458            frame.buffer.get(7, 2).and_then(|c| c.content.as_char()),
2459            Some('↓')
2460        );
2461    }
2462
2463    #[cfg(feature = "tracing")]
2464    #[test]
2465    fn list_tracing_span_and_selection_events_are_emitted() {
2466        let trace_state = Arc::new(Mutex::new(ListTraceState::default()));
2467        let _trace_test_guard = crate::tracing_test_support::acquire();
2468        let subscriber = tracing_subscriber::registry().with(ListTraceCapture {
2469            state: Arc::clone(&trace_state),
2470        });
2471        let _guard = tracing::subscriber::set_default(subscriber);
2472        tracing::callsite::rebuild_interest_cache();
2473
2474        let list = List::new(vec![
2475            ListItem::new("a"),
2476            ListItem::new("b"),
2477            ListItem::new("c"),
2478        ]);
2479        let mut state = ListState::default();
2480        state.select(Some(0));
2481        let mut pool = GraphemePool::new();
2482        let mut frame = Frame::new(10, 3, &mut pool);
2483        tracing::callsite::rebuild_interest_cache();
2484        StatefulWidget::render(&list, Rect::new(0, 0, 10, 3), &mut frame, &mut state);
2485        tracing::callsite::rebuild_interest_cache();
2486        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2487
2488        tracing::callsite::rebuild_interest_cache();
2489        let snapshot = trace_state.lock().expect("list trace state lock");
2490        assert!(snapshot.list_render_seen, "expected list.render span");
2491        assert!(
2492            snapshot.has_total_items_field,
2493            "list.render missing total_items"
2494        );
2495        assert!(
2496            snapshot.has_visible_items_field,
2497            "list.render missing visible_items"
2498        );
2499        assert!(
2500            snapshot.has_selected_count_field,
2501            "list.render missing selected_count"
2502        );
2503        assert!(
2504            snapshot.has_filter_active_field,
2505            "list.render missing filter_active"
2506        );
2507        assert!(
2508            snapshot.render_duration_recorded,
2509            "list.render did not record render_duration_us"
2510        );
2511        assert!(
2512            snapshot.selection_events >= 1,
2513            "expected list.selection debug event"
2514        );
2515    }
2516
2517    #[test]
2518    fn list_state_right_click_ignored() {
2519        let mut state = ListState::default();
2520        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Right), 5, 2);
2521        let hit = Some((HitId::new(1), HitRegion::Content, 3u64));
2522        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2523        assert_eq!(result, MouseResult::Ignored);
2524    }
2525
2526    #[test]
2527    fn list_state_click_border_region_ignored() {
2528        let mut state = ListState::default();
2529        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2530        let hit = Some((HitId::new(1), HitRegion::Border, 3u64));
2531        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2532        assert_eq!(result, MouseResult::Ignored);
2533    }
2534
2535    #[test]
2536    fn list_state_second_click_activates() {
2537        let mut state = ListState::default();
2538        state.select(Some(3));
2539
2540        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 2);
2541        let hit = Some((HitId::new(1), HitRegion::Content, 3u64));
2542        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2543        assert_eq!(result, MouseResult::Activated(3));
2544        assert_eq!(state.selected(), Some(3));
2545    }
2546
2547    /// With a hover stabilizer, one-cell jitter across a row boundary keeps
2548    /// the hovered row; a decisive move still switches within one event.
2549    #[test]
2550    fn list_state_hover_stabilizer_ignores_boundary_jitter() {
2551        let mut state =
2552            ListState::default().with_hover_stabilizer(HoverStabilizerConfig::default());
2553        let moved = |x, y| MouseEvent::new(MouseEventKind::Moved, x, y);
2554        let hit = |row: u64| Some((HitId::new(1), HitRegion::Content, row));
2555
2556        assert_eq!(
2557            state.handle_mouse(&moved(5, 3), hit(3), HitId::new(1), 20),
2558            MouseResult::HoverChanged
2559        );
2560        assert_eq!(state.hovered, Some(3));
2561
2562        // Jitter between rows 3 and 4 (one cell): the hovered row must not flip.
2563        for _ in 0..6 {
2564            assert_eq!(
2565                state.handle_mouse(&moved(5, 4), hit(4), HitId::new(1), 20),
2566                MouseResult::Ignored
2567            );
2568            assert_eq!(state.hovered, Some(3));
2569            assert_eq!(
2570                state.handle_mouse(&moved(5, 3), hit(3), HitId::new(1), 20),
2571                MouseResult::Ignored
2572            );
2573        }
2574        assert_eq!(
2575            state.hover_stabilizer().map(HoverStabilizer::switch_count),
2576            Some(1),
2577            "only the initial adoption counts as a switch"
2578        );
2579
2580        // A decisive move five rows down switches at once.
2581        assert_eq!(
2582            state.handle_mouse(&moved(5, 8), hit(8), HitId::new(1), 20),
2583            MouseResult::HoverChanged
2584        );
2585        assert_eq!(state.hovered, Some(8));
2586
2587        // Without a stabilizer the same jitter flips on every event.
2588        let mut raw = ListState::default();
2589        raw.handle_mouse(&moved(5, 3), hit(3), HitId::new(1), 20);
2590        assert_eq!(
2591            raw.handle_mouse(&moved(5, 4), hit(4), HitId::new(1), 20),
2592            MouseResult::HoverChanged
2593        );
2594        assert_eq!(raw.hovered, Some(4));
2595        assert!(raw.hover_stabilizer().is_none());
2596    }
2597
2598    #[test]
2599    fn list_state_hover_updates() {
2600        let mut state = ListState::default();
2601        let event = MouseEvent::new(MouseEventKind::Moved, 5, 2);
2602        let hit = Some((HitId::new(1), HitRegion::Content, 3u64));
2603        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2604        assert_eq!(result, MouseResult::HoverChanged);
2605        assert_eq!(state.hovered, Some(3));
2606    }
2607
2608    #[test]
2609    #[allow(clippy::field_reassign_with_default)]
2610    fn list_state_hover_same_index_ignored() {
2611        let mut state = {
2612            let mut s = ListState::default();
2613            s.hovered = Some(3);
2614            s
2615        };
2616        let event = MouseEvent::new(MouseEventKind::Moved, 5, 2);
2617        let hit = Some((HitId::new(1), HitRegion::Content, 3u64));
2618        let result = state.handle_mouse(&event, hit, HitId::new(1), 10);
2619        assert_eq!(result, MouseResult::Ignored);
2620        assert_eq!(state.hovered, Some(3));
2621    }
2622
2623    #[test]
2624    #[allow(clippy::field_reassign_with_default)]
2625    fn list_state_hover_clears() {
2626        let mut state = {
2627            let mut s = ListState::default();
2628            s.hovered = Some(5);
2629            s
2630        };
2631        let event = MouseEvent::new(MouseEventKind::Moved, 5, 2);
2632        // No hit (mouse moved off the list)
2633        let result = state.handle_mouse(&event, None, HitId::new(1), 10);
2634        assert_eq!(result, MouseResult::HoverChanged);
2635        assert_eq!(state.hovered, None);
2636    }
2637
2638    #[test]
2639    fn list_state_hover_clear_when_already_none() {
2640        let mut state = ListState::default();
2641        let event = MouseEvent::new(MouseEventKind::Moved, 5, 2);
2642        let result = state.handle_mouse(&event, None, HitId::new(1), 10);
2643        assert_eq!(result, MouseResult::Ignored);
2644    }
2645
2646    // --- bd-1lg.27: Selection & filter interaction tests ---
2647
2648    #[test]
2649    fn list_navigate_down_while_filter_active() {
2650        let list = List::new(vec![
2651            ListItem::new("alpha"),
2652            ListItem::new("banana"),
2653            ListItem::new("beta"),
2654            ListItem::new("gamma"),
2655        ]);
2656        let mut state = ListState::default();
2657        // Type "b" to filter → matches banana(1) and beta(2)
2658        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2659        assert_eq!(state.filter_query(), "b");
2660        // Selection should land on first match
2661        assert_eq!(state.selected(), Some(1)); // banana
2662
2663        // Navigate down in filtered list → should move to beta(2)
2664        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2665        assert_eq!(state.selected(), Some(2)); // beta
2666
2667        // Navigate down at end → should stay at beta(2)
2668        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2669        assert_eq!(state.selected(), Some(2));
2670    }
2671
2672    #[test]
2673    fn list_navigate_up_while_filter_active() {
2674        let list = List::new(vec![
2675            ListItem::new("alpha"),
2676            ListItem::new("banana"),
2677            ListItem::new("beta"),
2678            ListItem::new("gamma"),
2679        ]);
2680        let mut state = ListState::default();
2681        state.set_filter_query("b");
2682        // Force selection to beta(2) — last filtered match
2683        state.select(Some(2));
2684
2685        // Navigate up → should move to banana(1)
2686        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2687        assert_eq!(state.selected(), Some(1));
2688
2689        // Navigate up at top → should stay at banana(1)
2690        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2691        assert_eq!(state.selected(), Some(1));
2692    }
2693
2694    #[test]
2695    fn list_filter_case_insensitive() {
2696        let list = List::new(vec![
2697            ListItem::new("Alpha"),
2698            ListItem::new("BANANA"),
2699            ListItem::new("beta"),
2700        ]);
2701        let mut state = ListState::default();
2702        // Type uppercase 'B' → should match "BANANA" and "beta"
2703        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('B'))));
2704        assert_eq!(state.selected(), Some(1)); // BANANA is first match
2705    }
2706
2707    #[test]
2708    fn list_filter_matches_marker() {
2709        let list = List::new(vec![
2710            ListItem::new("apple").marker("fruit"),
2711            ListItem::new("carrot").marker("veggie"),
2712            ListItem::new("berry").marker("fruit"),
2713        ]);
2714        let mut state = ListState::default();
2715        // Type "veg" → should match only carrot (via marker)
2716        state.set_filter_query("veg");
2717        let filtered = list.filtered_indices(&mut state);
2718        assert_eq!(&*filtered, &[1]); // only carrot
2719    }
2720
2721    #[test]
2722    fn list_multi_select_toggle_while_filtered() {
2723        let list = List::new(vec![
2724            ListItem::new("alpha"),
2725            ListItem::new("banana"),
2726            ListItem::new("beta"),
2727            ListItem::new("gamma"),
2728        ]);
2729        let mut state = ListState::default();
2730        state.set_multi_select(true);
2731        state.set_filter_query("b");
2732
2733        // Select banana(1) first
2734        state.select(Some(1));
2735        // Toggle multi-select on banana
2736        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2737        assert!(state.selected_indices().contains(&1));
2738
2739        // Navigate to beta and toggle
2740        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2741        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2742        assert!(state.selected_indices().contains(&2));
2743        assert_eq!(state.selected_count(), 2);
2744    }
2745
2746    #[test]
2747    fn list_disable_multi_select_clears_extras() {
2748        let mut state = ListState::default();
2749        state.set_multi_select(true);
2750        state.toggle_multi_selected(0);
2751        state.toggle_multi_selected(1);
2752        state.toggle_multi_selected(2);
2753        assert_eq!(state.selected_count(), 3);
2754        // toggle_multi_selected sets selected to the last toggled index
2755        assert_eq!(state.selected(), Some(2));
2756
2757        // Disable multi-select → should keep only the current selection
2758        state.set_multi_select(false);
2759        assert_eq!(state.selected_count(), 1);
2760        assert!(state.selected_indices().contains(&2)); // current selected
2761    }
2762
2763    #[test]
2764    fn list_navigation_with_ctrl_modifier_ignored() {
2765        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2766        let mut state = ListState::default();
2767        state.select(Some(0));
2768
2769        let ctrl_down = KeyEvent {
2770            code: KeyCode::Down,
2771            modifiers: Modifiers::CTRL,
2772            kind: ftui_core::event::KeyEventKind::Press,
2773        };
2774        assert!(!list.handle_key(&mut state, &ctrl_down));
2775        assert_eq!(state.selected(), Some(0)); // unchanged
2776    }
2777
2778    #[test]
2779    fn list_space_with_no_selection_in_multi_select_is_noop() {
2780        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2781        let mut state = ListState::default();
2782        state.set_multi_select(true);
2783        // No selection
2784        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2785        assert_eq!(state.selected_count(), 0);
2786    }
2787
2788    #[test]
2789    fn list_backspace_on_empty_filter_returns_false() {
2790        let list = List::new(vec![ListItem::new("alpha")]);
2791        let mut state = ListState::default();
2792        assert!(state.filter_query().is_empty());
2793        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Backspace)));
2794    }
2795
2796    #[test]
2797    fn list_escape_on_empty_filter_returns_false() {
2798        let list = List::new(vec![ListItem::new("alpha")]);
2799        let mut state = ListState::default();
2800        assert!(state.filter_query().is_empty());
2801        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Escape)));
2802    }
2803
2804    #[test]
2805    fn list_navigate_in_empty_filtered_result() {
2806        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2807        let mut state = ListState::default();
2808        state.select(Some(0));
2809        state.set_filter_query("zzz"); // nothing matches
2810
2811        // Navigate should deselect since no filtered items
2812        let handled = list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down));
2813        // Either handled (deselected) or not, selection should be None
2814        if handled {
2815            assert_eq!(state.selected(), None);
2816        }
2817    }
2818
2819    #[test]
2820    fn list_filter_preserves_selection_when_still_visible() {
2821        let list = List::new(vec![
2822            ListItem::new("alpha"),
2823            ListItem::new("banana"),
2824            ListItem::new("beta"),
2825        ]);
2826        let mut state = ListState::default();
2827        state.select(Some(2)); // beta
2828
2829        // Type "b" → beta still matches, selection should stay
2830        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2831        assert_eq!(state.selected(), Some(2)); // beta still selected
2832    }
2833
2834    #[test]
2835    fn list_filter_moves_selection_when_current_hidden() {
2836        let list = List::new(vec![
2837            ListItem::new("alpha"),
2838            ListItem::new("banana"),
2839            ListItem::new("cherry"),
2840        ]);
2841        let mut state = ListState::default();
2842        state.select(Some(2)); // cherry
2843
2844        // Type "b" → cherry doesn't match, should move to banana(1)
2845        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2846        assert_eq!(state.selected(), Some(1)); // banana (first match)
2847    }
2848
2849    #[test]
2850    #[allow(clippy::field_reassign_with_default)]
2851    fn list_set_filter_query_resets_offset() {
2852        let mut state = ListState::default();
2853        state.offset = 10;
2854        state.set_filter_query("abc");
2855        assert_eq!(state.offset, 0);
2856        assert_eq!(state.filter_query(), "abc");
2857    }
2858
2859    #[test]
2860    fn list_clear_filter_query_resets_offset() {
2861        let mut state = ListState::default();
2862        state.set_filter_query("abc");
2863        state.offset = 5;
2864        state.clear_filter_query();
2865        assert_eq!(state.offset, 0);
2866        assert!(state.filter_query().is_empty());
2867    }
2868
2869    #[test]
2870    #[allow(clippy::field_reassign_with_default)]
2871    fn list_clear_filter_query_noop_when_empty() {
2872        let mut state = ListState::default();
2873        state.offset = 5;
2874        state.clear_filter_query(); // already empty
2875        assert_eq!(state.offset, 5); // unchanged
2876    }
2877
2878    #[test]
2879    fn list_select_next_in_multi_select_preserves_others() {
2880        let mut state = ListState::default();
2881        state.set_multi_select(true);
2882        state.toggle_multi_selected(0);
2883        state.toggle_multi_selected(2);
2884        // toggle_multi_selected sets selected to last toggled (2)
2885        assert_eq!(state.selected(), Some(2));
2886        assert_eq!(state.selected_count(), 2);
2887
2888        // Navigate down should not clear multi_selected
2889        state.select_next(5);
2890        assert_eq!(state.selected(), Some(3)); // moved from 2 to 3
2891        assert!(state.selected_indices().contains(&0));
2892        assert!(state.selected_indices().contains(&2));
2893    }
2894
2895    #[test]
2896    fn list_deselect_clears_multi_selected() {
2897        let mut state = ListState::default();
2898        state.set_multi_select(true);
2899        state.toggle_multi_selected(0);
2900        state.toggle_multi_selected(1);
2901        state.toggle_multi_selected(2);
2902        assert_eq!(state.selected_count(), 3);
2903
2904        state.select(None);
2905        assert_eq!(state.selected_count(), 0);
2906        assert!(state.selected_indices().is_empty());
2907    }
2908
2909    #[test]
2910    fn list_vi_j_moves_through_filtered_items() {
2911        let list = List::new(vec![
2912            ListItem::new("xylophone"),
2913            ListItem::new("berry"),
2914            ListItem::new("box"),
2915            ListItem::new("cat"),
2916        ]);
2917        let mut state = ListState::default();
2918        state.set_filter_query("b");
2919        // Filtered: berry(1), box(2)
2920        state.select(Some(1)); // berry
2921
2922        // j should move to box(2), skipping xylophone(0) and cat(3)
2923        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2924        assert_eq!(state.selected(), Some(2)); // box
2925
2926        // j at end → should stay at box(2)
2927        assert!(!list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2928        assert_eq!(state.selected(), Some(2));
2929    }
2930
2931    #[test]
2932    fn list_jk_navigate_not_filter_even_when_empty() {
2933        // j/k are always vi-navigation and must never be appended to the
2934        // filter query, even when the filter is empty. (bd-2pp0c)
2935        let list = List::new(vec![
2936            ListItem::new("alpha"),
2937            ListItem::new("jam"),
2938            ListItem::new("kite"),
2939        ]);
2940        let mut state = ListState::default();
2941        assert!(state.filter_query().is_empty());
2942
2943        // j navigates down, does NOT start a filter for "j"
2944        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2945        assert!(state.filter_query().is_empty());
2946        assert_eq!(state.selected(), Some(0)); // first selection from None
2947
2948        // j again moves to next item
2949        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2950        assert!(state.filter_query().is_empty());
2951        assert_eq!(state.selected(), Some(1));
2952
2953        // k navigates up, does NOT start a filter for "k"
2954        assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('k'))));
2955        assert!(state.filter_query().is_empty());
2956        assert_eq!(state.selected(), Some(0));
2957    }
2958
2959    #[test]
2960    fn list_multi_select_untoggle_removes_from_set() {
2961        let mut state = ListState::default();
2962        state.set_multi_select(true);
2963        state.select(Some(0));
2964        state.toggle_multi_selected(0);
2965        assert!(state.selected_indices().contains(&0));
2966        assert_eq!(state.selected_count(), 1);
2967
2968        // Toggle again removes from multi_selected
2969        state.toggle_multi_selected(0);
2970        assert!(!state.selected_indices().contains(&0));
2971    }
2972
2973    #[test]
2974    fn list_widget_render_uses_default_state() {
2975        let list = List::new(vec![ListItem::new("alpha"), ListItem::new("beta")]);
2976        let mut state = ListState::default();
2977        let mut pool = GraphemePool::new();
2978        let mut frame = Frame::new(10, 3, &mut pool);
2979        StatefulWidget::render(&list, Rect::new(0, 0, 10, 3), &mut frame, &mut state);
2980        // No selection, first item should render at row 0
2981        assert_eq!(row_text(&frame, 0), "alpha");
2982        assert_eq!(row_text(&frame, 1), "beta");
2983    }
2984}