ailloli_ui_widgets/files/
icons.rs

1//! File and directory icon selection backed by the Devicons font catalogue.
2
3use ailloli_ui_core::{Color, IconId};
4#[cfg(test)]
5use ailloli_ui_devicons_font::GENERIC_FILE_GLYPH;
6use ailloli_ui_devicons_font::{glyph_or_fallback, FOLDER_GLYPH};
7use ailloli_ui_fs::{FileEntry, FileKind};
8use devicons::FileIcon as DeviconsFileIcon;
9
10/// Icon identifier and optional recommended foreground tint.
11///
12/// `None` leaves tint choice to the caller. The helpers in this module always
13/// return `Some`: amber for directories, green for directory symlinks, the
14/// Devicons color for recognized files, or light gray for fallbacks.
15///
16/// # Examples
17///
18/// ```
19/// use ailloli_ui_core::{Color, IconId};
20/// use ailloli_ui_widgets::files::FileIconVisual;
21/// let visual = FileIconVisual::new(IconId::Plus, Some(Color::hex_rgb(0xffffff)));
22/// assert_eq!(visual.icon, IconId::Plus);
23/// assert!(visual.color.is_some());
24/// ```
25#[derive(Clone, Debug, PartialEq)]
26pub struct FileIconVisual {
27    /// Glyph source to paint.
28    pub icon: IconId,
29    /// Optional caller-overridable tint.
30    pub color: Option<Color>,
31}
32
33impl FileIconVisual {
34    /// Stores an icon and tint without normalization.
35    ///
36    /// # Examples
37    ///
38    /// ```
39    /// use ailloli_ui_core::IconId;
40    /// use ailloli_ui_widgets::files::FileIconVisual;
41    /// let visual = FileIconVisual::new(IconId::Close, None);
42    /// assert_eq!(visual.color, None);
43    /// ```
44    pub fn new(icon: IconId, color: Option<Color>) -> Self {
45        Self { icon, color }
46    }
47}
48
49/// Chooses an icon from an entry's kind, symlink target, and name.
50///
51/// Directory-like symlinks receive the folder glyph; other symlinks use their
52/// filename just like files. The recommended tint is discarded.
53///
54/// # Examples
55///
56/// ```
57/// use ailloli_ui_core::IconId;
58/// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
59/// use ailloli_ui_widgets::files::file_icon_for_entry;
60/// let entry = FileEntry::new(FileUri::parse("file:///repo/src")?, FileMetadata::new(FileKind::Directory));
61/// assert!(matches!(file_icon_for_entry(&entry), IconId::Devicon(_)));
62/// # Ok::<(), ailloli_ui_fs::FileError>(())
63/// ```
64pub fn file_icon_for_entry(entry: &FileEntry) -> IconId {
65    file_icon_visual_for_entry(entry).icon
66}
67
68/// Chooses a Devicons glyph for a filename, with a generic-file fallback.
69///
70/// Matching follows the upstream Devicons mapping and is based on the supplied
71/// name only; no filesystem access occurs. The recommended tint is discarded.
72///
73/// # Examples
74///
75/// ```
76/// use ailloli_ui_core::IconId;
77/// use ailloli_ui_widgets::files::file_icon_for_name;
78/// assert!(matches!(file_icon_for_name("main.rs"), IconId::Devicon(_)));
79/// assert!(matches!(file_icon_for_name("unknown"), IconId::Devicon(_)));
80/// ```
81pub fn file_icon_for_name(name: &str) -> IconId {
82    file_icon_visual_for_name(name).icon
83}
84
85/// Chooses both icon and recommended tint for a filesystem entry.
86///
87/// Real directories use amber (`#f59e0b`); symlinks known to target a
88/// directory use green (`#22c55e`). All other kinds use filename mapping.
89///
90/// # Examples
91///
92/// ```
93/// use ailloli_ui_core::Color;
94/// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
95/// use ailloli_ui_widgets::files::file_icon_visual_for_entry;
96/// let entry = FileEntry::new(FileUri::parse("file:///repo/src")?, FileMetadata::new(FileKind::Directory));
97/// assert_eq!(file_icon_visual_for_entry(&entry).color, Some(Color::hex_rgb(0xf59e0b)));
98/// # Ok::<(), ailloli_ui_fs::FileError>(())
99/// ```
100pub fn file_icon_visual_for_entry(entry: &FileEntry) -> FileIconVisual {
101    match (entry.metadata.kind, entry.metadata.symlink_target_kind) {
102        (FileKind::Symlink, Some(FileKind::Directory)) => {
103            FileIconVisual::new(IconId::Devicon(FOLDER_GLYPH), Some(symlink_folder_color()))
104        }
105        (FileKind::Directory, _) => {
106            FileIconVisual::new(IconId::Devicon(FOLDER_GLYPH), Some(folder_color()))
107        }
108        (FileKind::File | FileKind::Symlink | FileKind::Other, _) => {
109            file_icon_visual_for_name(&entry.name)
110        }
111    }
112}
113
114/// Chooses a filename glyph and its Devicons or fallback tint.
115///
116/// Missing source-font glyphs, wildcard mappings, and invalid upstream color
117/// strings fall back to the generic glyph/color (`#e5e7eb`).
118///
119/// # Examples
120///
121/// ```
122/// use ailloli_ui_core::Color;
123/// use ailloli_ui_widgets::files::file_icon_visual_for_name;
124/// assert_eq!(file_icon_visual_for_name("unknown").color, Some(Color::hex_rgb(0xe5e7eb)));
125/// ```
126pub fn file_icon_visual_for_name(name: &str) -> FileIconVisual {
127    let icon = DeviconsFileIcon::from(name);
128    let glyph = glyph_or_fallback(icon.icon);
129    let color = if icon.icon == '*' || glyph != icon.icon {
130        default_icon_color()
131    } else {
132        parse_devicon_color(icon.color)
133    };
134    FileIconVisual::new(IconId::Devicon(glyph), Some(color))
135}
136
137/// Parses an upstream Devicons color or returns the generic fallback color.
138fn parse_devicon_color(hex: &str) -> Color {
139    Color::hex(hex).unwrap_or_else(|_| default_icon_color())
140}
141
142/// Returns the fixed amber tint for real directories.
143fn folder_color() -> Color {
144    Color::hex_rgb(0xf59e0b)
145}
146
147/// Returns the fixed green tint for symlinks to directories.
148fn symlink_folder_color() -> Color {
149    Color::hex_rgb(0x22c55e)
150}
151
152/// Returns the light-gray tint for generic-file fallbacks.
153fn default_icon_color() -> Color {
154    Color::hex_rgb(0xe5e7eb)
155}
156
157#[cfg(test)]
158/// Verifies known extensions plus directory, symlink, color, and glyph fallbacks.
159mod tests {
160    use super::*;
161    use ailloli_ui_core::IconId;
162
163    #[test]
164    fn maps_supported_extensions_to_devicons_and_fallbacks() {
165        assert_eq!(file_icon_for_name("main.rs"), IconId::Devicon('\u{e68b}'));
166        assert_eq!(
167            file_icon_for_name("Cargo.toml"),
168            IconId::Devicon('\u{e6b2}')
169        );
170        assert_eq!(file_icon_for_name("README.md"), IconId::Devicon('\u{f48a}'));
171        assert_eq!(
172            file_icon_for_name("config.json"),
173            IconId::Devicon('\u{e60b}')
174        );
175        assert_eq!(file_icon_for_name("app.js"), IconId::Devicon('\u{e60c}'));
176        assert_eq!(file_icon_for_name("app.ts"), IconId::Devicon('\u{e628}'));
177        assert_eq!(
178            file_icon_for_name("index.html"),
179            IconId::Devicon('\u{e736}')
180        );
181        assert_eq!(file_icon_for_name("style.css"), IconId::Devicon('\u{e749}'));
182        assert_eq!(file_icon_for_name("unknown"), IconId::Devicon('\u{f15b}'));
183    }
184
185    #[test]
186    fn folders_use_nerd_font_folder_with_orange_tint() {
187        let entry = FileEntry {
188            uri: ailloli_ui_fs::FileUri::parse("file:///repo/src").expect("uri"),
189            name: "src".to_string(),
190            metadata: ailloli_ui_fs::FileMetadata::new(FileKind::Directory),
191        };
192        let visual = file_icon_visual_for_entry(&entry);
193        assert_eq!(visual.icon, IconId::Devicon(FOLDER_GLYPH));
194        assert_eq!(visual.color, Some(Color::hex_rgb(0xf59e0b)));
195    }
196
197    #[test]
198    fn symlink_directories_use_folder_with_green_tint() {
199        let mut metadata = ailloli_ui_fs::FileMetadata::new(FileKind::Symlink);
200        metadata.symlink_target_kind = Some(FileKind::Directory);
201        let entry = FileEntry {
202            uri: ailloli_ui_fs::FileUri::parse("file:///repo/bin").expect("uri"),
203            name: "bin".to_string(),
204            metadata,
205        };
206
207        let visual = file_icon_visual_for_entry(&entry);
208
209        assert_eq!(visual.icon, IconId::Devicon(FOLDER_GLYPH));
210        assert_eq!(visual.color, Some(Color::hex_rgb(0x22c55e)));
211    }
212
213    #[test]
214    fn file_visuals_include_devicons_color() {
215        let rust = file_icon_visual_for_name("main.rs");
216        assert_eq!(rust.icon, IconId::Devicon('\u{e68b}'));
217        assert_eq!(rust.color, Color::hex("#dea584").ok());
218
219        let unknown = file_icon_visual_for_name("file.unknownext");
220        assert_eq!(unknown.icon, IconId::Devicon('\u{f15b}'));
221        assert_eq!(unknown.color, Some(Color::hex_rgb(0xe5e7eb)));
222    }
223
224    #[test]
225    fn font_logos_and_source_missing_glyphs_use_the_generic_file_fallback() {
226        for name in ["PKGBUILD", "shell.nix", "vercel.json"] {
227            let visual = file_icon_visual_for_name(name);
228            assert_eq!(visual.icon, IconId::Devicon(GENERIC_FILE_GLYPH));
229            assert_eq!(visual.color, Some(Color::hex_rgb(0xe5e7eb)));
230        }
231    }
232}