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