Skip to main content

ftui_widgets/
file_picker.rs

1#![forbid(unsafe_code)]
2
3//! File picker widget for browsing and selecting files.
4//!
5//! Provides a TUI file browser with keyboard navigation. The widget
6//! renders a directory listing with cursor selection and supports
7//! entering subdirectories and navigating back to parents.
8//!
9//! # Architecture
10//!
11//! - [`FilePicker`] — stateless configuration and rendering
12//! - [`FilePickerState`] — mutable navigation state (cursor, directory, entries)
13//! - [`DirEntry`] — a single file/directory entry
14//!
15//! The widget uses [`StatefulWidget`] so the application owns the state
16//! and can read the selected path.
17
18use crate::{StatefulWidget, clear_text_area, clear_text_row, draw_text_span};
19use ftui_a11y::node::{A11yNodeInfo, A11yRole};
20use ftui_core::geometry::Rect;
21use ftui_render::frame::Frame;
22use ftui_style::Style;
23use std::{
24    io,
25    path::{Component, Path, PathBuf},
26};
27
28/// A single entry in a directory listing.
29#[derive(Debug, Clone, PartialEq, Eq)]
30pub struct DirEntry {
31    /// Display name.
32    pub name: String,
33    /// Full path.
34    pub path: PathBuf,
35    /// Whether this is a directory.
36    pub is_dir: bool,
37}
38
39impl DirEntry {
40    /// Create a directory entry.
41    pub fn dir(name: impl Into<String>, path: impl Into<PathBuf>) -> Self {
42        Self {
43            name: name.into(),
44            path: path.into(),
45            is_dir: true,
46        }
47    }
48
49    /// Create a file entry.
50    pub fn file(name: impl Into<String>, path: impl Into<PathBuf>) -> Self {
51        Self {
52            name: name.into(),
53            path: path.into(),
54            is_dir: false,
55        }
56    }
57}
58
59/// Mutable state for the file picker.
60#[derive(Debug, Clone)]
61pub struct FilePickerState {
62    /// Current directory being displayed.
63    pub current_dir: PathBuf,
64    /// Root directory for confinement (if set, cannot navigate above this).
65    pub root: Option<PathBuf>,
66    /// Directory entries (sorted: dirs first, then files).
67    pub entries: Vec<DirEntry>,
68    /// Currently highlighted index.
69    pub cursor: usize,
70    /// Scroll offset (first visible row).
71    pub offset: usize,
72    /// The selected/confirmed path (set when user presses enter on a file).
73    pub selected: Option<PathBuf>,
74    /// Whether this picker currently owns keyboard focus.
75    pub focused: bool,
76    /// Navigation history for going back.
77    history: Vec<(PathBuf, usize)>,
78}
79
80impl FilePickerState {
81    /// Create a new state with the given directory and entries.
82    pub fn new(current_dir: PathBuf, entries: Vec<DirEntry>) -> Self {
83        Self {
84            current_dir,
85            root: None,
86            entries,
87            cursor: 0,
88            offset: 0,
89            selected: None,
90            focused: false,
91            history: Vec::new(),
92        }
93    }
94
95    /// Mark whether this picker currently owns keyboard focus.
96    #[must_use]
97    pub fn with_focused(mut self, focused: bool) -> Self {
98        self.focused = focused;
99        self
100    }
101
102    /// Update keyboard focus ownership.
103    pub fn set_focused(&mut self, focused: bool) {
104        self.focused = focused;
105    }
106
107    /// Set a root directory to confine navigation.
108    ///
109    /// When set, the user cannot navigate to a parent directory above this root.
110    #[must_use]
111    pub fn with_root(mut self, root: impl Into<PathBuf>) -> Self {
112        self.root = Some(root.into());
113        self
114    }
115
116    /// Create state from a directory path by reading the filesystem.
117    ///
118    /// Sorts entries: directories first (alphabetical), then files (alphabetical).
119    /// Returns an error if the directory cannot be read.
120    pub fn from_path(path: impl AsRef<Path>) -> std::io::Result<Self> {
121        let path = path.as_ref().to_path_buf();
122        let entries = read_directory(&path)?;
123        Ok(Self::new(path, entries))
124    }
125
126    /// Move cursor up.
127    pub fn cursor_up(&mut self) {
128        if self.cursor > 0 {
129            self.cursor -= 1;
130        }
131    }
132
133    /// Move cursor down.
134    pub fn cursor_down(&mut self) {
135        if !self.entries.is_empty() && self.cursor < self.entries.len() - 1 {
136            self.cursor += 1;
137        }
138    }
139
140    /// Move cursor to the first entry.
141    pub fn cursor_home(&mut self) {
142        self.cursor = 0;
143    }
144
145    /// Move cursor to the last entry.
146    pub fn cursor_end(&mut self) {
147        if !self.entries.is_empty() {
148            self.cursor = self.entries.len() - 1;
149        }
150    }
151
152    /// Page up by `page_size` rows.
153    pub fn page_up(&mut self, page_size: usize) {
154        self.cursor = self.cursor.saturating_sub(page_size);
155    }
156
157    /// Page down by `page_size` rows.
158    pub fn page_down(&mut self, page_size: usize) {
159        if !self.entries.is_empty() {
160            self.cursor = (self.cursor + page_size).min(self.entries.len() - 1);
161        }
162    }
163
164    /// Enter the selected directory (if cursor is on a directory).
165    ///
166    /// Returns `Ok(true)` if navigation succeeded, `Ok(false)` if cursor is on a file,
167    /// or an error if the directory cannot be read.
168    pub fn enter(&mut self) -> std::io::Result<bool> {
169        let Some(entry) = self.entries.get(self.cursor) else {
170            return Ok(false);
171        };
172
173        if !entry.is_dir {
174            if let Some(root) = &self.root {
175                ensure_path_within_root(
176                    &entry.path,
177                    root,
178                    "Cannot select a file outside root directory",
179                )?;
180            }
181            self.selected = Some(entry.path.clone());
182            return Ok(false);
183        }
184
185        let new_dir = entry.path.clone();
186
187        if let Some(root) = &self.root {
188            ensure_path_within_root(
189                &new_dir,
190                root,
191                "Cannot traverse outside root directory via symlink",
192            )?;
193        }
194
195        let new_entries = read_directory(&new_dir)?;
196
197        self.history.push((self.current_dir.clone(), self.cursor));
198        self.current_dir = new_dir;
199        self.entries = new_entries;
200        self.cursor = 0;
201        self.offset = 0;
202        Ok(true)
203    }
204
205    /// Go back to the parent directory.
206    ///
207    /// Returns `Ok(true)` if navigation succeeded.
208    pub fn go_back(&mut self) -> std::io::Result<bool> {
209        // If root is set, prevent going above it using canonicalized paths
210        if let Some(root) = &self.root {
211            let (resolved_curr, resolved_root) = canonicalize_candidate_and_root(
212                &self.current_dir,
213                root,
214                "current file picker directory",
215            )?;
216            if resolved_curr == resolved_root || !resolved_curr.starts_with(&resolved_root) {
217                return Ok(false);
218            }
219        }
220
221        if let Some((prev_dir, prev_cursor)) = self.history.last().cloned() {
222            if let Some(root) = &self.root {
223                ensure_path_within_root(
224                    &prev_dir,
225                    root,
226                    "Cannot restore directory outside root directory",
227                )?;
228            }
229            self.history.pop();
230            let entries = read_directory(&prev_dir)?;
231            self.current_dir = prev_dir;
232            self.entries = entries;
233            self.cursor = prev_cursor.min(self.entries.len().saturating_sub(1));
234            self.offset = 0;
235            return Ok(true);
236        }
237
238        // No history — try parent directory. `Path::parent` is lexical: for
239        // `.` or a relative `src` it is the empty path, which cannot be read,
240        // and for `a/..` it is `a`. Those take the parent of the resolved path.
241        let lexical_parent = match self.current_dir.components().next_back() {
242            Some(Component::Normal(_)) => self
243                .current_dir
244                .parent()
245                .filter(|parent| !parent.as_os_str().is_empty())
246                .map(Path::to_path_buf),
247            _ => None,
248        };
249        let parent = match lexical_parent {
250            Some(parent) => Some(parent),
251            None => std::fs::canonicalize(&self.current_dir)?
252                .parent()
253                .map(Path::to_path_buf),
254        };
255        if let Some(parent) = parent {
256            if let Some(root) = &self.root
257                && !path_is_within_root(&parent, root)?
258            {
259                return Ok(false); // Block parent traversal outside root
260            }
261
262            let entries = read_directory(&parent)?;
263            self.current_dir = parent;
264            self.entries = entries;
265            self.cursor = 0;
266            self.offset = 0;
267            return Ok(true);
268        }
269
270        Ok(false)
271    }
272
273    /// Ensure scroll offset keeps cursor visible for the given viewport height.
274    fn adjust_scroll(&mut self, visible_rows: usize) {
275        // `entries`, `cursor` and `offset` are public, so a caller may shrink
276        // the listing under them. Rendering slices `entries[offset..]`, which
277        // panicked once `offset` was past the end.
278        self.cursor = self.cursor.min(self.entries.len().saturating_sub(1));
279        if self.cursor < self.offset {
280            self.offset = self.cursor;
281        }
282        if visible_rows == 0 {
283            return;
284        }
285        if self.cursor >= self.offset + visible_rows {
286            self.offset = self.cursor + 1 - visible_rows;
287        }
288    }
289}
290
291fn canonicalize_for_confinement(path: &Path, label: &str) -> io::Result<PathBuf> {
292    std::fs::canonicalize(path).map_err(|error| {
293        io::Error::new(
294            error.kind(),
295            format!("Cannot resolve {label} {}: {error}", path.display()),
296        )
297    })
298}
299
300fn canonicalize_candidate_and_root(
301    candidate: &Path,
302    root: &Path,
303    label: &str,
304) -> io::Result<(PathBuf, PathBuf)> {
305    let resolved_candidate = canonicalize_for_confinement(candidate, label)?;
306    let resolved_root = canonicalize_for_confinement(root, "file picker root")?;
307    Ok((resolved_candidate, resolved_root))
308}
309
310fn path_is_within_root(candidate: &Path, root: &Path) -> io::Result<bool> {
311    let (resolved_candidate, resolved_root) =
312        canonicalize_candidate_and_root(candidate, root, "file picker path")?;
313    Ok(resolved_candidate.starts_with(resolved_root))
314}
315
316fn ensure_path_within_root(candidate: &Path, root: &Path, message: &str) -> io::Result<()> {
317    if path_is_within_root(candidate, root)? {
318        return Ok(());
319    }
320
321    Err(io::Error::new(io::ErrorKind::PermissionDenied, message))
322}
323
324/// Read a directory and return sorted entries (dirs first, then files).
325fn read_directory(path: &Path) -> std::io::Result<Vec<DirEntry>> {
326    let mut dirs = Vec::new();
327    let mut files = Vec::new();
328
329    for entry in std::fs::read_dir(path)? {
330        let entry = entry?;
331        let name = entry.file_name().to_string_lossy().to_string();
332        let mut file_type = entry.file_type()?;
333        let full_path = entry.path();
334
335        // If it's a symlink, check what it points to
336        if file_type.is_symlink()
337            && let Ok(metadata) = std::fs::metadata(&full_path)
338        {
339            file_type = metadata.file_type();
340        }
341
342        if file_type.is_dir() {
343            dirs.push(DirEntry::dir(name, full_path));
344        } else {
345            files.push(DirEntry::file(name, full_path));
346        }
347    }
348
349    dirs.sort_by_key(|a| a.name.to_lowercase());
350    files.sort_by_key(|a| a.name.to_lowercase());
351
352    dirs.extend(files);
353    Ok(dirs)
354}
355
356/// Configuration and rendering for the file picker widget.
357///
358/// # Example
359///
360/// ```ignore
361/// let picker = FilePicker::new()
362///     .dir_style(Style::new().fg(PackedRgba::rgb(100, 100, 255)))
363///     .cursor_style(Style::new().bold());
364///
365/// let mut state = FilePickerState::from_path(".").unwrap();
366/// picker.render(area, &mut frame, &mut state);
367/// ```
368#[derive(Debug, Clone)]
369pub struct FilePicker {
370    /// Style for directory entries.
371    pub dir_style: Style,
372    /// Style for file entries.
373    pub file_style: Style,
374    /// Style for the cursor row.
375    pub cursor_style: Style,
376    /// Style for the header (current directory).
377    pub header_style: Style,
378    /// Whether to show the current directory path as a header.
379    pub show_header: bool,
380    /// Prefix for directory entries.
381    pub dir_prefix: &'static str,
382    /// Prefix for file entries.
383    pub file_prefix: &'static str,
384    /// Optional stable accessibility identity for this picker.
385    pub accessibility_id: Option<u64>,
386}
387
388impl Default for FilePicker {
389    fn default() -> Self {
390        Self {
391            dir_style: Style::default(),
392            file_style: Style::default(),
393            cursor_style: Style::default(),
394            header_style: Style::default(),
395            show_header: true,
396            dir_prefix: "📁 ",
397            file_prefix: "  ",
398            accessibility_id: None,
399        }
400    }
401}
402
403impl FilePicker {
404    /// Create a new file picker with default styles.
405    pub fn new() -> Self {
406        Self::default()
407    }
408
409    /// Set the directory entry style.
410    #[must_use]
411    pub fn dir_style(mut self, style: Style) -> Self {
412        self.dir_style = style;
413        self
414    }
415
416    /// Set the file entry style.
417    #[must_use]
418    pub fn file_style(mut self, style: Style) -> Self {
419        self.file_style = style;
420        self
421    }
422
423    /// Set the cursor (highlight) style.
424    #[must_use]
425    pub fn cursor_style(mut self, style: Style) -> Self {
426        self.cursor_style = style;
427        self
428    }
429
430    /// Set the header style.
431    #[must_use]
432    pub fn header_style(mut self, style: Style) -> Self {
433        self.header_style = style;
434        self
435    }
436
437    /// Toggle header display.
438    #[must_use]
439    pub fn show_header(mut self, show: bool) -> Self {
440        self.show_header = show;
441        self
442    }
443
444    /// Give this picker a stable accessibility identity.
445    #[must_use]
446    pub fn accessibility_id(mut self, id: u64) -> Self {
447        self.accessibility_id = Some(id);
448        self
449    }
450
451    fn accessibility_root_id(&self, area: Rect) -> u64 {
452        self.accessibility_id
453            .unwrap_or_else(|| A11yNodeInfo::stable_id_for(A11yRole::List, area))
454    }
455
456    fn accessibility_entry_id(parent: u64, entry: &DirEntry) -> u64 {
457        use std::hash::{Hash, Hasher};
458        let mut hasher = std::collections::hash_map::DefaultHasher::new();
459        ("ftui.file_picker.entry", parent, &entry.path).hash(&mut hasher);
460        hasher.finish()
461    }
462
463    fn emit_accessibility(
464        &self,
465        area: Rect,
466        entries_y: u16,
467        visible_rows: usize,
468        frame: &mut Frame,
469        state: &FilePickerState,
470    ) {
471        if !frame.a11y_enabled() {
472            return;
473        }
474        let bounds = area.intersection(&frame.buffer.current_scissor());
475        if bounds.is_empty() {
476            return;
477        }
478        let root_id = self.accessibility_root_id(area);
479        let root = A11yNodeInfo::new(root_id, A11yRole::List, bounds)
480            .with_name(format!("Files in {}", state.current_dir.display()))
481            .with_description(format!("{} entries", state.entries.len()));
482        frame.with_a11y_scope(root, |frame| {
483            if state.entries.is_empty() {
484                let empty_bounds = Rect::new(area.x, entries_y, area.width, 1)
485                    .intersection(&frame.buffer.current_scissor());
486                if !empty_bounds.is_empty() {
487                    frame.push_a11y(
488                        A11yNodeInfo::new(
489                            Self::accessibility_entry_id(
490                                root_id,
491                                &DirEntry::file("(empty directory)", state.current_dir.clone()),
492                            ),
493                            A11yRole::Label,
494                            empty_bounds,
495                        )
496                        .with_name("Empty directory"),
497                    );
498                }
499                return;
500            }
501
502            let end_idx = (state.offset + visible_rows).min(state.entries.len());
503            for (row, entry) in state.entries[state.offset..end_idx].iter().enumerate() {
504                let actual_idx = state.offset + row;
505                let y = entries_y.saturating_add(row as u16);
506                let item_bounds = Rect::new(area.x, y, area.width, 1)
507                    .intersection(&frame.buffer.current_scissor());
508                if item_bounds.is_empty() {
509                    continue;
510                }
511                let mut node = A11yNodeInfo::new(
512                    Self::accessibility_entry_id(root_id, entry),
513                    A11yRole::ListItem,
514                    item_bounds,
515                )
516                .with_name(&entry.name)
517                .with_description(if entry.is_dir { "Directory" } else { "File" });
518                node.state.selected = actual_idx == state.cursor;
519                node.state.focused = state.focused && actual_idx == state.cursor;
520                frame.push_a11y(node);
521            }
522        });
523    }
524}
525
526impl StatefulWidget for FilePicker {
527    type State = FilePickerState;
528
529    fn render(&self, area: Rect, frame: &mut Frame, state: &mut Self::State) {
530        if area.is_empty() {
531            return;
532        }
533
534        let entries_y = area.y.saturating_add(if self.show_header { 1 } else { 0 });
535        let visible_rows = area.bottom().saturating_sub(entries_y) as usize;
536        state.adjust_scroll(visible_rows);
537        self.emit_accessibility(area, entries_y, visible_rows, frame, state);
538
539        let deg = frame.buffer.degradation;
540        if !deg.render_content() {
541            return;
542        }
543
544        clear_text_area(frame, area, Style::default());
545
546        let header_style = if deg.apply_styling() {
547            self.header_style
548        } else {
549            Style::default()
550        };
551        let dir_style = if deg.apply_styling() {
552            self.dir_style
553        } else {
554            Style::default()
555        };
556        let file_style = if deg.apply_styling() {
557            self.file_style
558        } else {
559            Style::default()
560        };
561        let cursor_style = if deg.apply_styling() {
562            self.cursor_style
563        } else {
564            Style::default()
565        };
566
567        let mut y = area.y;
568        let max_y = area.bottom();
569
570        // Header: current directory path
571        if self.show_header && y < max_y {
572            clear_text_row(frame, Rect::new(area.x, y, area.width, 1), header_style);
573            let header = state.current_dir.to_string_lossy();
574            draw_text_span(frame, area.x, y, &header, header_style, area.right());
575            y += 1;
576        }
577
578        if y >= max_y {
579            return;
580        }
581
582        let visible_rows = (max_y - y) as usize;
583
584        if state.entries.is_empty() {
585            clear_text_row(frame, Rect::new(area.x, y, area.width, 1), file_style);
586            draw_text_span(
587                frame,
588                area.x,
589                y,
590                "(empty directory)",
591                file_style,
592                area.right(),
593            );
594            return;
595        }
596
597        let end_idx = (state.offset + visible_rows).min(state.entries.len());
598        for (i, entry) in state.entries[state.offset..end_idx].iter().enumerate() {
599            if y >= max_y {
600                break;
601            }
602
603            let actual_idx = state.offset + i;
604            let is_cursor = actual_idx == state.cursor;
605
606            let prefix = if entry.is_dir {
607                self.dir_prefix
608            } else {
609                self.file_prefix
610            };
611
612            let base_style = if entry.is_dir { dir_style } else { file_style };
613
614            let style = if is_cursor {
615                cursor_style.merge(&base_style)
616            } else {
617                base_style
618            };
619
620            clear_text_row(frame, Rect::new(area.x, y, area.width, 1), style);
621
622            // Draw cursor indicator
623            let mut x = area.x;
624            if is_cursor {
625                draw_text_span(frame, x, y, "> ", cursor_style, area.right());
626                x = x.saturating_add(2);
627            } else {
628                x = x.saturating_add(2);
629            }
630
631            // Draw prefix + name
632            x = draw_text_span(frame, x, y, prefix, style, area.right());
633            draw_text_span(frame, x, y, &entry.name, style, area.right());
634
635            y += 1;
636        }
637    }
638}
639
640#[cfg(test)]
641mod tests {
642    use super::*;
643    use ftui_a11y::tree::{A11yTree, A11yTreeBuilder, AnnouncementReason, ScreenReaderPolicy};
644    use ftui_render::grapheme_pool::GraphemePool;
645
646    fn buf_to_lines(buf: &ftui_render::buffer::Buffer) -> Vec<String> {
647        let mut lines = Vec::new();
648        for y in 0..buf.height() {
649            let mut row = String::with_capacity(buf.width() as usize);
650            for x in 0..buf.width() {
651                let ch = buf
652                    .get(x, y)
653                    .and_then(|c| c.content.as_char())
654                    .unwrap_or(' ');
655                row.push(ch);
656            }
657            lines.push(row);
658        }
659        lines
660    }
661
662    fn make_entries() -> Vec<DirEntry> {
663        vec![
664            DirEntry::dir("docs", "/tmp/docs"),
665            DirEntry::dir("src", "/tmp/src"),
666            DirEntry::file("README.md", "/tmp/README.md"),
667            DirEntry::file("main.rs", "/tmp/main.rs"),
668        ]
669    }
670
671    fn make_state() -> FilePickerState {
672        FilePickerState::new(PathBuf::from("/tmp"), make_entries())
673    }
674
675    fn render_picker_a11y(
676        picker: &FilePicker,
677        state: &mut FilePickerState,
678        area: Rect,
679    ) -> A11yTree {
680        let mut builder = A11yTreeBuilder::new();
681        {
682            let mut pool = GraphemePool::new();
683            let mut frame = Frame::new(80, 24, &mut pool);
684            frame.set_a11y(&mut builder);
685            picker.render(area, &mut frame, state);
686            frame.finish_a11y();
687        }
688        builder.build()
689    }
690
691    #[test]
692    fn file_picker_accessibility_exposes_list_and_entry_kinds() {
693        let picker = FilePicker::new().accessibility_id(7100);
694        let mut state = make_state().with_focused(true);
695        let tree = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 6));
696        assert_eq!(tree.root_id(), Some(7100));
697        let root = tree.root().unwrap();
698        assert_eq!(root.role, A11yRole::List);
699        assert!(root.name.as_deref().unwrap().contains("/tmp"));
700        assert_eq!(root.children.len(), 4);
701        let first = tree.node(root.children[0]).unwrap();
702        assert_eq!(first.name.as_deref(), Some("docs"));
703        assert_eq!(first.description.as_deref(), Some("Directory"));
704        assert!(first.state.selected && first.state.focused);
705        let file = tree.node(root.children[2]).unwrap();
706        assert_eq!(file.description.as_deref(), Some("File"));
707        assert_eq!(tree.focused_id(), Some(first.id));
708    }
709
710    #[test]
711    fn file_picker_cursor_focus_announces_once_when_focused() {
712        let picker = FilePicker::new().show_header(false).accessibility_id(7101);
713        let mut state = make_state().with_focused(true);
714        let before = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
715        state.cursor_down();
716        let after = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
717        let batch = after.screen_reader_announcements_since(&before, ScreenReaderPolicy::default());
718        assert_eq!(batch.announcements.len(), 1);
719        assert_eq!(batch.dropped_count, 0);
720        assert_eq!(
721            batch.announcements[0].reason,
722            AnnouncementReason::FocusChanged
723        );
724        assert!(batch.announcements[0].text.contains("src"));
725    }
726
727    #[test]
728    fn file_picker_selection_is_silent_when_widget_does_not_own_focus() {
729        let picker = FilePicker::new().show_header(false).accessibility_id(7102);
730        let mut state = make_state();
731        let before = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
732        assert!(before.focused().is_none());
733        state.cursor_down();
734        let after = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
735        assert!(after.focused().is_none());
736        assert!(
737            after
738                .screen_reader_announcements_since(&before, ScreenReaderPolicy::default())
739                .announcements
740                .is_empty()
741        );
742        let root = after.root().unwrap();
743        assert!(after.node(root.children[1]).unwrap().state.selected);
744    }
745
746    #[test]
747    fn file_picker_entry_ids_survive_resize_and_scroll() {
748        let picker = FilePicker::new().show_header(false).accessibility_id(7103);
749        let mut state = make_state().with_focused(true);
750        let before = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 2));
751        let docs_id = before.focused_id().unwrap();
752        let before_root = before.root_id();
753        state.cursor_down();
754        state.cursor_down();
755        let after = render_picker_a11y(&picker, &mut state, Rect::new(4, 3, 50, 2));
756        assert_eq!(before_root, after.root_id());
757        // Scroll changes which entries are present, but a logical path keeps
758        // the same ID whenever it is rendered again.
759        state.cursor_home();
760        let again = render_picker_a11y(&picker, &mut state, Rect::new(1, 1, 60, 3));
761        assert_eq!(again.focused_id(), Some(docs_id));
762    }
763
764    #[test]
765    fn file_picker_directory_change_replaces_focused_entry_identity() {
766        let picker = FilePicker::new().show_header(false).accessibility_id(7104);
767        let mut state = make_state().with_focused(true);
768        let before = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
769        state.current_dir = PathBuf::from("/other");
770        state.entries = vec![DirEntry::file("different.txt", "/other/different.txt")];
771        state.cursor = 0;
772        state.offset = 0;
773        let after = render_picker_a11y(&picker, &mut state, Rect::new(0, 0, 40, 4));
774        assert_ne!(before.focused_id(), after.focused_id());
775        let batch = after.screen_reader_announcements_since(&before, ScreenReaderPolicy::default());
776        assert_eq!(batch.announcements.len(), 1);
777        assert!(batch.announcements[0].text.contains("different.txt"));
778    }
779
780    #[test]
781    fn dir_entry_constructors() {
782        let d = DirEntry::dir("src", "/src");
783        assert!(d.is_dir);
784        assert_eq!(d.name, "src");
785
786        let f = DirEntry::file("main.rs", "/main.rs");
787        assert!(!f.is_dir);
788        assert_eq!(f.name, "main.rs");
789    }
790
791    #[test]
792    fn state_cursor_movement() {
793        let mut state = make_state();
794        assert_eq!(state.cursor, 0);
795
796        state.cursor_down();
797        assert_eq!(state.cursor, 1);
798
799        state.cursor_down();
800        state.cursor_down();
801        assert_eq!(state.cursor, 3);
802
803        // Can't go past end
804        state.cursor_down();
805        assert_eq!(state.cursor, 3);
806
807        state.cursor_up();
808        assert_eq!(state.cursor, 2);
809
810        state.cursor_home();
811        assert_eq!(state.cursor, 0);
812
813        // Can't go before start
814        state.cursor_up();
815        assert_eq!(state.cursor, 0);
816
817        state.cursor_end();
818        assert_eq!(state.cursor, 3);
819    }
820
821    #[test]
822    fn state_page_navigation() {
823        let entries: Vec<DirEntry> = (0..20)
824            .map(|i| DirEntry::file(format!("file{i}.txt"), format!("/tmp/file{i}.txt")))
825            .collect();
826        let mut state = FilePickerState::new(PathBuf::from("/tmp"), entries);
827
828        state.page_down(5);
829        assert_eq!(state.cursor, 5);
830
831        state.page_down(5);
832        assert_eq!(state.cursor, 10);
833
834        state.page_up(3);
835        assert_eq!(state.cursor, 7);
836
837        state.page_up(100);
838        assert_eq!(state.cursor, 0);
839
840        state.page_down(100);
841        assert_eq!(state.cursor, 19);
842    }
843
844    #[test]
845    fn state_empty_entries() {
846        let mut state = FilePickerState::new(PathBuf::from("/tmp"), vec![]);
847        state.cursor_down(); // should not panic
848        state.cursor_up();
849        state.cursor_end();
850        state.cursor_home();
851        state.page_down(10);
852        state.page_up(10);
853        assert_eq!(state.cursor, 0);
854    }
855
856    #[test]
857    fn adjust_scroll_keeps_cursor_visible() {
858        let entries: Vec<DirEntry> = (0..20)
859            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
860            .collect();
861        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
862
863        state.cursor = 15;
864        state.adjust_scroll(5);
865        // cursor=15 should be visible in a 5-row window
866        assert!(state.offset <= 15);
867        assert!(state.offset + 5 > 15);
868
869        state.cursor = 0;
870        state.adjust_scroll(5);
871        assert_eq!(state.offset, 0);
872    }
873
874    #[test]
875    fn render_basic() {
876        let picker = FilePicker::new().show_header(false);
877        let mut state = make_state();
878
879        let area = Rect::new(0, 0, 30, 5);
880        let mut pool = GraphemePool::new();
881        let mut frame = Frame::new(30, 5, &mut pool);
882
883        picker.render(area, &mut frame, &mut state);
884        let lines = buf_to_lines(&frame.buffer);
885
886        // First entry should have cursor indicator "> "
887        assert!(lines[0].starts_with("> "));
888        // Should contain directory and file names
889        let all_text = lines.join("\n");
890        assert!(all_text.contains("docs"));
891        assert!(all_text.contains("src"));
892        assert!(all_text.contains("README.md"));
893        assert!(all_text.contains("main.rs"));
894    }
895
896    #[test]
897    fn render_with_header() {
898        let picker = FilePicker::new().show_header(true);
899        let mut state = make_state();
900
901        let area = Rect::new(0, 0, 30, 6);
902        let mut pool = GraphemePool::new();
903        let mut frame = Frame::new(30, 6, &mut pool);
904
905        picker.render(area, &mut frame, &mut state);
906        let lines = buf_to_lines(&frame.buffer);
907
908        // First line should be the directory path
909        assert!(lines[0].starts_with("/tmp"));
910    }
911
912    #[test]
913    fn render_empty_directory() {
914        let picker = FilePicker::new().show_header(false);
915        let mut state = FilePickerState::new(PathBuf::from("/empty"), vec![]);
916
917        let area = Rect::new(0, 0, 30, 3);
918        let mut pool = GraphemePool::new();
919        let mut frame = Frame::new(30, 3, &mut pool);
920
921        picker.render(area, &mut frame, &mut state);
922        let lines = buf_to_lines(&frame.buffer);
923
924        assert!(lines[0].contains("empty directory"));
925    }
926
927    #[test]
928    fn render_scrolling() {
929        let entries: Vec<DirEntry> = (0..20)
930            .map(|i| DirEntry::file(format!("file{i:02}.txt"), format!("/tmp/file{i:02}.txt")))
931            .collect();
932        let mut state = FilePickerState::new(PathBuf::from("/tmp"), entries);
933        let picker = FilePicker::new().show_header(false);
934
935        // Move cursor to item 15, viewport is 5 rows
936        state.cursor = 15;
937        let area = Rect::new(0, 0, 30, 5);
938        let mut pool = GraphemePool::new();
939        let mut frame = Frame::new(30, 5, &mut pool);
940
941        picker.render(area, &mut frame, &mut state);
942        let lines = buf_to_lines(&frame.buffer);
943
944        // file15 should be visible (with cursor)
945        let all_text = lines.join("\n");
946        assert!(all_text.contains("file15"));
947    }
948
949    #[test]
950    fn cursor_style_applied_to_selected_row() {
951        use ftui_render::cell::PackedRgba;
952
953        let picker = FilePicker::new()
954            .show_header(false)
955            .cursor_style(Style::new().fg(PackedRgba::rgb(255, 0, 0)));
956        let mut state = make_state();
957        state.cursor = 1; // "src"
958
959        let area = Rect::new(0, 0, 30, 4);
960        let mut pool = GraphemePool::new();
961        let mut frame = Frame::new(30, 4, &mut pool);
962
963        picker.render(area, &mut frame, &mut state);
964
965        // The cursor row (y=1) should have the cursor indicator
966        let lines = buf_to_lines(&frame.buffer);
967        assert!(lines[1].starts_with("> "));
968        // Non-cursor rows should not
969        assert!(!lines[0].starts_with("> "));
970    }
971
972    #[test]
973    fn selected_set_on_file_entry() {
974        let mut state = make_state();
975        state.cursor = 2; // README.md (a file)
976
977        // enter() on a file should set selected
978        let result = state.enter();
979        assert!(result.is_ok());
980        assert_eq!(state.selected, Some(PathBuf::from("/tmp/README.md")));
981    }
982
983    #[test]
984    fn enter_on_file_rejects_canonical_path_outside_root() {
985        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
986        let repo = root
987            .parent()
988            .and_then(Path::parent)
989            .expect("crate should be under workspace crates directory");
990        let outside_file = repo.join("Cargo.toml");
991        let mut state = FilePickerState::new(
992            root.clone(),
993            vec![DirEntry::file("Cargo.toml", outside_file)],
994        )
995        .with_root(root);
996
997        let error = state
998            .enter()
999            .expect_err("root confinement should reject outside file selections");
1000
1001        assert_eq!(error.kind(), std::io::ErrorKind::PermissionDenied);
1002        assert!(state.selected.is_none());
1003    }
1004
1005    #[test]
1006    fn enter_on_directory_with_unresolvable_root_fails_closed() {
1007        let current_dir = std::env::current_dir().expect("test should run inside the workspace");
1008        let missing_root =
1009            current_dir.join(format!(".missing-file-picker-root-{}", std::process::id()));
1010        let target_dir = std::env::temp_dir();
1011        let mut state = FilePickerState::new(
1012            current_dir.clone(),
1013            vec![DirEntry::dir("tmp", target_dir.clone())],
1014        )
1015        .with_root(missing_root);
1016
1017        let error = state
1018            .enter()
1019            .expect_err("unresolvable confinement root should fail closed");
1020
1021        assert_eq!(error.kind(), std::io::ErrorKind::NotFound);
1022        assert_eq!(state.current_dir, current_dir);
1023        assert_eq!(state.entries[0].path, target_dir);
1024    }
1025
1026    #[test]
1027    fn go_back_from_a_relative_directory_reaches_its_parent() {
1028        // Tests run in the crate directory, which holds `src`.
1029        let crate_dir = std::fs::canonicalize(".").expect("crate directory");
1030        for relative in ["src", ".", "src/.."] {
1031            let mut state = FilePickerState::from_path(relative).expect("readable directory");
1032            assert!(state.go_back().expect("parent is readable"), "{relative}");
1033            let expected = if relative == "src" {
1034                crate_dir.clone()
1035            } else {
1036                crate_dir
1037                    .parent()
1038                    .expect("crate has a parent")
1039                    .to_path_buf()
1040            };
1041            assert_eq!(
1042                std::fs::canonicalize(&state.current_dir).expect("resolvable"),
1043                expected,
1044                "{relative}"
1045            );
1046        }
1047    }
1048
1049    #[test]
1050    fn render_survives_entries_shrinking_under_cursor_and_offset() {
1051        let mut state = make_state();
1052        state.cursor = 40;
1053        state.offset = 30;
1054        let mut pool = GraphemePool::new();
1055        let mut frame = Frame::new(20, 5, &mut pool);
1056        FilePicker::new().render(Rect::new(0, 0, 20, 5), &mut frame, &mut state);
1057        assert_eq!(state.cursor, state.entries.len() - 1);
1058        assert!(state.offset <= state.cursor);
1059    }
1060
1061    // ── DirEntry edge cases ───────────────────────────────────────
1062
1063    #[test]
1064    fn dir_entry_equality() {
1065        let a = DirEntry::dir("src", "/src");
1066        let b = DirEntry::dir("src", "/src");
1067        assert_eq!(a, b);
1068
1069        let c = DirEntry::file("src", "/src");
1070        assert_ne!(a, c, "dir vs file should differ");
1071    }
1072
1073    #[test]
1074    fn dir_entry_clone() {
1075        let orig = DirEntry::file("main.rs", "/main.rs");
1076        let cloned = orig.clone();
1077        assert_eq!(orig, cloned);
1078    }
1079
1080    #[test]
1081    fn dir_entry_debug_format() {
1082        let e = DirEntry::dir("test", "/test");
1083        let dbg = format!("{e:?}");
1084        assert!(dbg.contains("test"));
1085        assert!(dbg.contains("is_dir: true"));
1086    }
1087
1088    // ── FilePickerState construction ──────────────────────────────
1089
1090    #[test]
1091    fn state_new_defaults() {
1092        let state = FilePickerState::new(PathBuf::from("/home"), vec![]);
1093        assert_eq!(state.current_dir, PathBuf::from("/home"));
1094        assert_eq!(state.cursor, 0);
1095        assert_eq!(state.offset, 0);
1096        assert!(state.selected.is_none());
1097        assert!(state.root.is_none());
1098        assert!(state.entries.is_empty());
1099    }
1100
1101    #[test]
1102    fn state_with_root_sets_root() {
1103        let state = FilePickerState::new(PathBuf::from("/home/user"), vec![]).with_root("/home");
1104        assert_eq!(state.root, Some(PathBuf::from("/home")));
1105    }
1106
1107    // ── Cursor on single entry ────────────────────────────────────
1108
1109    #[test]
1110    fn cursor_movement_single_entry() {
1111        let entries = vec![DirEntry::file("only.txt", "/only.txt")];
1112        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1113
1114        assert_eq!(state.cursor, 0);
1115        state.cursor_down();
1116        assert_eq!(state.cursor, 0, "can't go past single entry");
1117        state.cursor_up();
1118        assert_eq!(state.cursor, 0);
1119        state.cursor_end();
1120        assert_eq!(state.cursor, 0);
1121        state.cursor_home();
1122        assert_eq!(state.cursor, 0);
1123    }
1124
1125    #[test]
1126    fn page_down_clamps_to_last() {
1127        let entries: Vec<DirEntry> = (0..5)
1128            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
1129            .collect();
1130        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1131
1132        state.page_down(100);
1133        assert_eq!(state.cursor, 4);
1134    }
1135
1136    #[test]
1137    fn page_up_clamps_to_zero() {
1138        let entries: Vec<DirEntry> = (0..5)
1139            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
1140            .collect();
1141        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1142        state.cursor = 3;
1143
1144        state.page_up(100);
1145        assert_eq!(state.cursor, 0);
1146    }
1147
1148    #[test]
1149    fn page_operations_on_empty_entries() {
1150        let mut state = FilePickerState::new(PathBuf::from("/"), vec![]);
1151        state.page_down(10);
1152        assert_eq!(state.cursor, 0);
1153        state.page_up(10);
1154        assert_eq!(state.cursor, 0);
1155    }
1156
1157    // ── enter() edge cases ────────────────────────────────────────
1158
1159    #[test]
1160    fn enter_on_empty_entries_returns_false() {
1161        let mut state = FilePickerState::new(PathBuf::from("/"), vec![]);
1162        let result = state.enter();
1163        assert!(result.is_ok());
1164        assert!(!result.unwrap());
1165        assert!(state.selected.is_none());
1166    }
1167
1168    #[test]
1169    fn enter_on_file_sets_selected_without_navigation() {
1170        let entries = vec![
1171            DirEntry::dir("sub", "/sub"),
1172            DirEntry::file("readme.txt", "/readme.txt"),
1173        ];
1174        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1175        state.cursor = 1;
1176
1177        let result = state.enter().unwrap();
1178        assert!(!result, "enter on file returns false (no navigation)");
1179        assert_eq!(state.selected, Some(PathBuf::from("/readme.txt")));
1180        // Current directory unchanged.
1181        assert_eq!(state.current_dir, PathBuf::from("/"));
1182    }
1183
1184    // ── go_back() edge cases ──────────────────────────────────────
1185
1186    #[test]
1187    fn go_back_blocked_at_root() {
1188        let root = std::env::temp_dir();
1189        let mut state = FilePickerState::new(root.clone(), vec![]).with_root(root);
1190
1191        let changed = state.go_back().unwrap();
1192        assert!(!changed, "go_back should be blocked when already at root");
1193    }
1194
1195    #[test]
1196    fn go_back_without_history_uses_parent_directory() {
1197        let current = std::env::temp_dir();
1198        let parent = current
1199            .parent()
1200            .expect("temp_dir should have a parent")
1201            .to_path_buf();
1202
1203        let mut state = FilePickerState::new(current.clone(), vec![]);
1204        let changed = state.go_back().unwrap();
1205
1206        assert!(
1207            changed,
1208            "go_back should navigate to parent when history is empty"
1209        );
1210        assert_eq!(state.current_dir, parent);
1211        assert_eq!(state.cursor, 0, "parent navigation resets cursor to home");
1212    }
1213
1214    #[test]
1215    fn go_back_restores_history_cursor_with_clamp() {
1216        let child = std::env::temp_dir();
1217        let parent = child
1218            .parent()
1219            .expect("temp_dir should have a parent")
1220            .to_path_buf();
1221
1222        let mut state = FilePickerState::new(
1223            parent.clone(),
1224            vec![
1225                DirEntry::file("placeholder.txt", parent.join("placeholder.txt")),
1226                DirEntry::dir("child", child.clone()),
1227            ],
1228        );
1229        state.cursor = 1;
1230
1231        let entered = state.enter().unwrap();
1232        assert!(entered, "enter should navigate into selected directory");
1233
1234        let went_back = state.go_back().unwrap();
1235        assert!(
1236            went_back,
1237            "go_back should restore previous directory from history"
1238        );
1239        assert_eq!(state.current_dir, parent);
1240
1241        let expected_cursor = 1.min(state.entries.len().saturating_sub(1));
1242        assert_eq!(state.cursor, expected_cursor);
1243    }
1244
1245    // ── adjust_scroll edge cases ──────────────────────────────────
1246
1247    #[test]
1248    fn adjust_scroll_zero_visible_rows_is_noop() {
1249        let entries: Vec<DirEntry> = (0..10)
1250            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
1251            .collect();
1252        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1253        state.cursor = 5;
1254        state.offset = 0;
1255
1256        state.adjust_scroll(0);
1257        assert_eq!(
1258            state.offset, 0,
1259            "zero visible rows should not change offset"
1260        );
1261    }
1262
1263    #[test]
1264    fn adjust_scroll_cursor_above_viewport() {
1265        let entries: Vec<DirEntry> = (0..20)
1266            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
1267            .collect();
1268        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1269        state.offset = 10;
1270        state.cursor = 5;
1271
1272        state.adjust_scroll(5);
1273        assert_eq!(state.offset, 5, "offset should snap to cursor");
1274    }
1275
1276    #[test]
1277    fn adjust_scroll_cursor_below_viewport() {
1278        let entries: Vec<DirEntry> = (0..20)
1279            .map(|i| DirEntry::file(format!("f{i}"), format!("/f{i}")))
1280            .collect();
1281        let mut state = FilePickerState::new(PathBuf::from("/"), entries);
1282        state.offset = 0;
1283        state.cursor = 10;
1284
1285        state.adjust_scroll(5);
1286        // cursor=10 should be the last visible row: offset + 5 > 10 → offset = 6
1287        assert_eq!(state.offset, 6);
1288    }
1289
1290    // ── FilePicker builder ────────────────────────────────────────
1291
1292    #[test]
1293    fn file_picker_default_values() {
1294        let picker = FilePicker::default();
1295        assert!(picker.show_header);
1296        assert_eq!(picker.dir_prefix, "📁 ");
1297        assert_eq!(picker.file_prefix, "  ");
1298    }
1299
1300    #[test]
1301    fn file_picker_builder_chain() {
1302        let picker = FilePicker::new()
1303            .dir_style(Style::default())
1304            .file_style(Style::default())
1305            .cursor_style(Style::default())
1306            .header_style(Style::default())
1307            .show_header(false);
1308        assert!(!picker.show_header);
1309    }
1310
1311    #[test]
1312    fn file_picker_debug_format() {
1313        let picker = FilePicker::new();
1314        let dbg = format!("{picker:?}");
1315        assert!(dbg.contains("FilePicker"));
1316    }
1317
1318    // ── Render edge cases ─────────────────────────────────────────
1319
1320    #[test]
1321    fn render_zero_area_is_noop() {
1322        let picker = FilePicker::new();
1323        let mut state = make_state();
1324
1325        let area = Rect::new(0, 0, 0, 0);
1326        let mut pool = GraphemePool::new();
1327        let mut frame = Frame::new(30, 5, &mut pool);
1328
1329        picker.render(area, &mut frame, &mut state);
1330        // No crash, buffer untouched.
1331        let lines = buf_to_lines(&frame.buffer);
1332        assert!(lines[0].trim().is_empty());
1333    }
1334
1335    #[test]
1336    fn render_height_one_shows_only_header() {
1337        let picker = FilePicker::new().show_header(true);
1338        let mut state = make_state();
1339
1340        let area = Rect::new(0, 0, 30, 1);
1341        let mut pool = GraphemePool::new();
1342        let mut frame = Frame::new(30, 5, &mut pool);
1343
1344        picker.render(area, &mut frame, &mut state);
1345        let lines = buf_to_lines(&frame.buffer);
1346        // Only the header row should have content.
1347        assert!(lines[0].starts_with("/tmp"));
1348        // Row 1 should be empty (no room for entries).
1349        assert!(lines[1].trim().is_empty());
1350    }
1351
1352    #[test]
1353    fn render_no_header_uses_full_area_for_entries() {
1354        let picker = FilePicker::new().show_header(false);
1355        let mut state = make_state();
1356
1357        let area = Rect::new(0, 0, 30, 4);
1358        let mut pool = GraphemePool::new();
1359        let mut frame = Frame::new(30, 4, &mut pool);
1360
1361        picker.render(area, &mut frame, &mut state);
1362        let lines = buf_to_lines(&frame.buffer);
1363        // First line should be an entry (cursor on first entry), not a header.
1364        assert!(lines[0].starts_with("> "));
1365    }
1366
1367    #[test]
1368    fn render_cursor_on_last_entry() {
1369        let picker = FilePicker::new().show_header(false);
1370        let mut state = make_state();
1371        state.cursor = 3; // last entry: main.rs
1372
1373        let area = Rect::new(0, 0, 30, 5);
1374        let mut pool = GraphemePool::new();
1375        let mut frame = Frame::new(30, 5, &mut pool);
1376
1377        picker.render(area, &mut frame, &mut state);
1378        let lines = buf_to_lines(&frame.buffer);
1379        // The cursor row should contain "main.rs".
1380        let cursor_line = lines.iter().find(|l| l.starts_with("> ")).unwrap();
1381        assert!(cursor_line.contains("main.rs"));
1382    }
1383
1384    #[test]
1385    fn render_area_offset() {
1386        // Render into a sub-area of a larger buffer.
1387        let picker = FilePicker::new().show_header(false);
1388        let mut state = make_state();
1389
1390        let area = Rect::new(5, 2, 20, 3);
1391        let mut pool = GraphemePool::new();
1392        let mut frame = Frame::new(30, 10, &mut pool);
1393
1394        picker.render(area, &mut frame, &mut state);
1395        let lines = buf_to_lines(&frame.buffer);
1396        // Rows 0 and 1 should be empty (area starts at y=2).
1397        assert!(lines[0].trim().is_empty());
1398        assert!(lines[1].trim().is_empty());
1399        // Row 2 should have content starting at x=5.
1400        assert!(lines[2].len() >= 7);
1401    }
1402
1403    #[test]
1404    fn render_shorter_header_and_fewer_entries_clear_stale_content() {
1405        let picker = FilePicker::new().show_header(true);
1406        let mut state = FilePickerState::new(PathBuf::from("/tmp/very/long/path"), make_entries());
1407
1408        let area = Rect::new(0, 0, 24, 4);
1409        let mut pool = GraphemePool::new();
1410        let mut frame = Frame::new(24, 4, &mut pool);
1411
1412        picker.render(area, &mut frame, &mut state);
1413
1414        state.current_dir = PathBuf::from("/x");
1415        state.entries = vec![DirEntry::file("a", "/x/a")];
1416        state.cursor = 0;
1417        state.offset = 0;
1418
1419        picker.render(area, &mut frame, &mut state);
1420        let lines = buf_to_lines(&frame.buffer);
1421
1422        assert_eq!(lines[0], format!("{:<24}", "/x"));
1423        assert!(lines[1].starts_with(">   a"));
1424        assert_eq!(lines[2], " ".repeat(24));
1425        assert_eq!(lines[3], " ".repeat(24));
1426    }
1427}