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::{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#[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 #[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 #[must_use]
56 pub fn style(mut self, style: Style) -> Self {
57 self.style = style;
58 self
59 }
60
61 #[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#[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 hit_id: Option<HitId>,
87 data_hash: Option<u64>,
89}
90
91impl<'a> List<'a> {
92 #[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 #[must_use]
113 pub fn data_hash(mut self, hash: u64) -> Self {
114 self.data_hash = Some(hash);
115 self
116 }
117
118 #[must_use]
120 pub fn block(mut self, block: Block<'a>) -> Self {
121 self.block = Some(block);
122 self
123 }
124
125 #[must_use]
127 pub fn style(mut self, style: Style) -> Self {
128 self.style = style;
129 self
130 }
131
132 #[must_use]
134 pub fn highlight_style(mut self, style: Style) -> Self {
135 self.highlight_style = style;
136 self
137 }
138
139 #[must_use]
141 pub fn hover_style(mut self, style: Style) -> Self {
142 self.hover_style = style;
143 self
144 }
145
146 #[must_use]
148 pub fn highlight_symbol(mut self, symbol: &'a str) -> Self {
149 self.highlight_symbol = Some(symbol);
150 self
151 }
152
153 #[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 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 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 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 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 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#[derive(Debug, Clone)]
378pub struct ListState {
379 undo_id: UndoWidgetId,
381 pub selected: Option<usize>,
383 pub hovered: Option<usize>,
385 hover_stabilizer: Option<HoverStabilizer>,
387 pub offset: usize,
389 persistence_id: Option<String>,
391 scroll_into_view_requested: bool,
393 filter_query: String,
395 multi_select_enabled: bool,
397 multi_selected: BTreeSet<usize>,
399 #[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 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 #[inline]
442 #[must_use = "use the selected index (if any)"]
443 pub fn selected(&self) -> Option<usize> {
444 self.selected
445 }
446
447 #[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 #[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 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 #[must_use]
477 pub const fn multi_select_enabled(&self) -> bool {
478 self.multi_select_enabled
479 }
480
481 #[must_use]
483 pub fn filter_query(&self) -> &str {
484 &self.filter_query
485 }
486
487 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 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 #[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 #[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 #[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 #[must_use]
558 pub fn hover_stabilizer(&self) -> Option<&HoverStabilizer> {
559 self.hover_stabilizer.as_ref()
560 }
561
562 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 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 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 pub fn scroll_up(&mut self, lines: usize) {
653 self.offset = self.offset.saturating_sub(lines);
654 }
655
656 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 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 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#[derive(Clone, Debug, Default, PartialEq)]
714#[cfg_attr(
715 feature = "state-persistence",
716 derive(serde::Serialize, serde::Deserialize)
717)]
718pub struct ListPersistState {
719 pub selected: Option<usize>,
721 pub offset: usize,
723 pub filter_query: String,
725 pub multi_select_enabled: bool,
727 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_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 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 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 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 let row_area = Rect::new(list_area.x, y, list_area.width, 1);
903 clear_text_row(frame, row_area, item_style);
904
905 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 if !symbol.is_empty() {
916 x = draw_text_span(frame, x, y, symbol, item_style, list_area.right());
917 x = draw_text_span(frame, x, y, " ", item_style, list_area.right());
919 }
920
921 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 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 let marker_width = display_width(self.marker) as u16;
1050 let space_after_marker = if self.marker.is_empty() { 0u16 } else { 1 };
1051
1052 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 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 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 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 let inner_available = Size::new(
1094 available.width.saturating_sub(chrome_width),
1095 available.height.saturating_sub(chrome_height),
1096 );
1097
1098 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 if let Some(symbol) = self.highlight_symbol {
1110 let symbol_width = display_width(symbol) as u16 + 1; max_width = max_width.saturating_add(symbol_width);
1112 }
1113
1114 let preferred_width = max_width.saturating_add(chrome_width);
1116 let preferred_height = total_height.saturating_add(chrome_height);
1117
1118 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, }
1126 }
1127
1128 fn has_intrinsic_size(&self) -> bool {
1129 !self.items.is_empty()
1130 }
1131}
1132
1133#[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 #[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 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)); StatefulWidget::render(&list, area, &mut frame, &mut state);
1434 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 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 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); state.select(None);
1501 assert_eq!(state.offset, 0); }
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 state.select(Some(8));
1517 StatefulWidget::render(&list, area, &mut frame, &mut state);
1518 assert!(state.offset > 0);
1519
1520 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 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 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 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 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 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); 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 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); let mut state = ListState::default();
1626 StatefulWidget::render(&list, area, &mut frame, &mut state);
1627
1628 assert!(frame.hit_test(5, 0).is_none());
1630 }
1631
1632 use crate::MeasurableWidget;
1635 use ftui_core::geometry::Size;
1636
1637 #[test]
1638 fn list_item_measure_simple() {
1639 let item = ListItem::new("Hello"); 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("•"); 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")]; 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"), ListItem::new("LongerItem"), ListItem::new("Tiny"), ];
1688 let list = List::new(items);
1689 let constraints = list.measure(Size::MAX);
1690
1691 assert_eq!(constraints.preferred.width, 10);
1693 assert_eq!(constraints.preferred.height, 3);
1695 }
1696
1697 #[test]
1698 fn list_measure_with_block() {
1699 let block = crate::block::Block::bordered(); let items = vec![ListItem::new("Hi")]; let list = List::new(items).block(block);
1702 let constraints = list.measure(Size::MAX);
1703
1704 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")]; let list = List::new(items).highlight_symbol(">"); let constraints = list.measure(Size::MAX);
1715
1716 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 assert_eq!(constraints.min.height, 1);
1737 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 #[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 state.select(Some(10));
1777 state.offset = 8;
1778 assert_eq!(state.selected(), Some(10));
1779 assert_eq!(state.offset, 8);
1780
1781 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); }
1799
1800 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 state.select(None);
1828 assert_eq!(state.selected, None);
1829 assert_eq!(state.offset, 0);
1830
1831 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 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); }
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)); }
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); }
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)); }
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 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2025 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 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2041 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 #[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 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 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 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 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 #[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 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2391 assert_eq!(state.filter_query(), "b");
2392 assert_eq!(state.selected(), Some(1)); assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down)));
2397 assert_eq!(state.selected(), Some(2)); 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 state.select(Some(2));
2416
2417 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Up)));
2419 assert_eq!(state.selected(), Some(1));
2420
2421 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 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('B'))));
2436 assert_eq!(state.selected(), Some(1)); }
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 state.set_filter_query("veg");
2449 let filtered = list.filtered_indices(&mut state);
2450 assert_eq!(&*filtered, &[1]); }
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 state.select(Some(1));
2467 assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char(' '))));
2469 assert!(state.selected_indices().contains(&1));
2470
2471 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 assert_eq!(state.selected(), Some(2));
2488
2489 state.set_multi_select(false);
2491 assert_eq!(state.selected_count(), 1);
2492 assert!(state.selected_indices().contains(&2)); }
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)); }
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 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"); let handled = list.handle_key(&mut state, &KeyEvent::new(KeyCode::Down));
2545 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)); assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2563 assert_eq!(state.selected(), Some(2)); }
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)); assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('b'))));
2578 assert_eq!(state.selected(), Some(1)); }
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(); assert_eq!(state.offset, 5); }
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 assert_eq!(state.selected(), Some(2));
2618 assert_eq!(state.selected_count(), 2);
2619
2620 state.select_next(5);
2622 assert_eq!(state.selected(), Some(3)); 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 state.select(Some(1)); assert!(list.handle_key(&mut state, &KeyEvent::new(KeyCode::Char('j'))));
2656 assert_eq!(state.selected(), Some(2)); 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 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 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)); 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 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 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 assert_eq!(row_text(&frame, 0), "alpha");
2714 assert_eq!(row_text(&frame, 1), "beta");
2715 }
2716}