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