Skip to main content

ftui_widgets/
spinner.rs

1#![forbid(unsafe_code)]
2
3//! Spinner widget.
4
5use crate::block::Block;
6use crate::{StatefulWidget, Widget, clear_text_area};
7use ftui_core::geometry::Rect;
8use ftui_render::frame::Frame;
9use ftui_style::Style;
10use ftui_text::display_width;
11
12/// Braille dot spinner animation frames.
13pub const DOTS: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
14/// ASCII line spinner animation frames.
15pub const LINE: &[&str] = &["|", "/", "-", "\\"];
16
17/// A widget to display a spinner.
18#[derive(Debug, Clone, Default)]
19pub struct Spinner<'a> {
20    block: Option<Block<'a>>,
21    style: Style,
22    frames: &'a [&'a str],
23    label: Option<&'a str>,
24}
25
26impl<'a> Spinner<'a> {
27    /// Create a new spinner with default dot frames.
28    pub fn new() -> Self {
29        Self {
30            block: None,
31            style: Style::default(),
32            frames: DOTS,
33            label: None,
34        }
35    }
36
37    /// Wrap the spinner in a [`Block`] container.
38    #[must_use]
39    pub fn block(mut self, block: Block<'a>) -> Self {
40        self.block = Some(block);
41        self
42    }
43
44    /// Set the base style for the spinner.
45    #[must_use]
46    pub fn style(mut self, style: Style) -> Self {
47        self.style = style;
48        self
49    }
50
51    /// Set the animation frame characters.
52    #[must_use]
53    pub fn frames(mut self, frames: &'a [&'a str]) -> Self {
54        self.frames = frames;
55        self
56    }
57
58    /// Set a text label displayed next to the spinner.
59    #[must_use]
60    pub fn label(mut self, label: &'a str) -> Self {
61        self.label = Some(label);
62        self
63    }
64
65    fn frame_for_render(&self, current_frame: usize, use_unicode: bool) -> Option<&'a str> {
66        if self.frames.is_empty() {
67            return None;
68        }
69
70        let frame_idx = current_frame % self.frames.len();
71        if use_unicode {
72            return Some(self.frames[frame_idx]);
73        }
74
75        let candidate = self.frames[frame_idx];
76        if candidate.is_ascii() {
77            Some(candidate)
78        } else {
79            self.frames
80                .iter()
81                .copied()
82                .find(|frame| frame.is_ascii())
83                .or(Some("*"))
84        }
85    }
86}
87
88/// Mutable state for a [`Spinner`] widget.
89#[derive(Debug, Clone, Default)]
90pub struct SpinnerState {
91    /// Index of the currently displayed animation frame.
92    pub current_frame: usize,
93}
94
95impl SpinnerState {
96    /// Advance to the next animation frame.
97    pub fn tick(&mut self) {
98        self.current_frame = self.current_frame.wrapping_add(1);
99    }
100}
101
102impl<'a> StatefulWidget for Spinner<'a> {
103    type State = SpinnerState;
104
105    fn render(&self, area: Rect, frame: &mut Frame, state: &mut Self::State) {
106        // Not for an empty area: nothing lands on screen for one, so a node
107        // would describe a widget that was never drawn, and every such node
108        // collides on the id of the same empty rect
109        // (bd-a11y-sibling-id-collision-6zqd2).
110        if frame.a11y_enabled() && !area.is_empty() {
111            frame.push_a11y_nodes(ftui_a11y::Accessible::accessibility_nodes(self, area));
112        }
113        #[cfg(feature = "tracing")]
114        let _span = tracing::debug_span!(
115            "widget_render",
116            widget = "Spinner",
117            x = area.x,
118            y = area.y,
119            w = area.width,
120            h = area.height
121        )
122        .entered();
123
124        let deg = frame.buffer.degradation;
125
126        // Skeleton+: skip entirely (spinner is decorative)
127        if !deg.render_content() {
128            clear_text_area(frame, area, Style::default());
129            return;
130        }
131
132        // EssentialOnly: spinner is decorative, only show label text
133        if !deg.render_decorative() {
134            clear_text_area(frame, area, Style::default());
135            if let Some(label) = self.label {
136                crate::draw_text_span(frame, area.x, area.y, label, Style::default(), area.right());
137            }
138            return;
139        }
140
141        let style = if deg.apply_styling() {
142            self.style
143        } else {
144            Style::default()
145        };
146
147        clear_text_area(frame, area, style);
148
149        let spinner_area = match &self.block {
150            Some(b) => {
151                crate::render_block_without_a11y(b, area, frame);
152                b.inner(area)
153            }
154            None => area,
155        };
156
157        if spinner_area.is_empty() {
158            return;
159        }
160
161        let mut x = spinner_area.left();
162        let y = spinner_area.top();
163        if let Some(frame_char) =
164            self.frame_for_render(state.current_frame, deg.use_unicode_borders())
165        {
166            crate::draw_text_span(frame, x, y, frame_char, style, spinner_area.right());
167            let w = display_width(frame_char);
168            x += w as u16;
169        }
170
171        // Render label
172        if let Some(label) = self.label {
173            if x > spinner_area.left() {
174                x += 1;
175            }
176            if x < spinner_area.right() {
177                crate::draw_text_span(frame, x, y, label, style, spinner_area.right());
178            }
179        }
180    }
181}
182
183impl<'a> Widget for Spinner<'a> {
184    fn render(&self, area: Rect, frame: &mut Frame) {
185        let mut state = SpinnerState::default();
186        StatefulWidget::render(self, area, frame, &mut state);
187    }
188}
189
190// ============================================================================
191// Accessibility
192// ============================================================================
193
194impl ftui_a11y::Accessible for Spinner<'_> {
195    fn accessibility_nodes(&self, area: Rect) -> Vec<ftui_a11y::node::A11yNodeInfo> {
196        use ftui_a11y::node::{A11yNodeInfo, A11yRole, A11yState};
197
198        let id = crate::a11y_node_id(area);
199        let name = self
200            .label
201            .map(|l| format!("Loading: {l}"))
202            .unwrap_or_else(|| "Loading...".to_owned());
203        let node = A11yNodeInfo::new(id, A11yRole::ProgressBar, area)
204            .with_name(name)
205            .with_state(A11yState {
206                busy: true,
207                ..A11yState::default()
208            });
209        vec![node]
210    }
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216    use ftui_render::buffer::Buffer;
217    use ftui_render::grapheme_pool::GraphemePool;
218
219    fn cell_char(buf: &Buffer, x: u16, y: u16) -> Option<char> {
220        buf.get(x, y).and_then(|c| c.content.as_char())
221    }
222
223    fn raw_row_text(buf: &Buffer, y: u16, width: u16) -> String {
224        (0..width)
225            .map(|x| {
226                buf.get(x, y)
227                    .and_then(|c| c.content.as_char())
228                    .unwrap_or(' ')
229            })
230            .collect()
231    }
232
233    // --- SpinnerState tests ---
234
235    #[test]
236    fn state_default() {
237        let state = SpinnerState::default();
238        assert_eq!(state.current_frame, 0);
239    }
240
241    #[test]
242    fn state_tick_increments() {
243        let mut state = SpinnerState::default();
244        state.tick();
245        assert_eq!(state.current_frame, 1);
246        state.tick();
247        assert_eq!(state.current_frame, 2);
248    }
249
250    #[test]
251    fn state_tick_wraps_on_overflow() {
252        let mut state = SpinnerState {
253            current_frame: usize::MAX,
254        };
255        state.tick();
256        assert_eq!(state.current_frame, 0);
257    }
258
259    // --- Builder tests ---
260
261    #[test]
262    fn default_uses_dots_frames() {
263        let spinner = Spinner::new();
264        assert_eq!(spinner.frames.len(), DOTS.len());
265        assert_eq!(spinner.frames, DOTS);
266    }
267
268    #[test]
269    fn custom_frames() {
270        let frames: &[&str] = &["A", "B", "C"];
271        let spinner = Spinner::new().frames(frames);
272        assert_eq!(spinner.frames.len(), 3);
273    }
274
275    #[test]
276    fn builder_label() {
277        let spinner = Spinner::new().label("Loading...");
278        assert_eq!(spinner.label, Some("Loading..."));
279    }
280
281    // --- Rendering tests ---
282
283    #[test]
284    fn render_zero_area() {
285        let spinner = Spinner::new();
286        let area = Rect::new(0, 0, 0, 0);
287        let mut pool = GraphemePool::new();
288        let mut frame = Frame::new(1, 1, &mut pool);
289        Widget::render(&spinner, area, &mut frame);
290        // Should not panic
291    }
292
293    #[test]
294    fn stateless_render_uses_frame_zero() {
295        let frames: &[&str] = &["A", "B", "C"];
296        let spinner = Spinner::new().frames(frames);
297        let area = Rect::new(0, 0, 5, 1);
298        let mut pool = GraphemePool::new();
299        let mut frame = Frame::new(5, 1, &mut pool);
300        Widget::render(&spinner, area, &mut frame);
301
302        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('A'));
303    }
304
305    #[test]
306    fn stateful_render_cycles_frames() {
307        let frames: &[&str] = &["X", "Y", "Z"];
308        let spinner = Spinner::new().frames(frames);
309        let area = Rect::new(0, 0, 5, 1);
310
311        // Frame 0 -> "X"
312        let mut pool = GraphemePool::new();
313        let mut frame = Frame::new(5, 1, &mut pool);
314        let mut state = SpinnerState { current_frame: 0 };
315        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
316        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('X'));
317
318        // Frame 1 -> "Y"
319        let mut pool = GraphemePool::new();
320        let mut frame = Frame::new(5, 1, &mut pool);
321        state.current_frame = 1;
322        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
323        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('Y'));
324
325        // Frame 2 -> "Z"
326        let mut pool = GraphemePool::new();
327        let mut frame = Frame::new(5, 1, &mut pool);
328        state.current_frame = 2;
329        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
330        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('Z'));
331
332        // Frame 3 wraps -> "X"
333        let mut pool = GraphemePool::new();
334        let mut frame = Frame::new(5, 1, &mut pool);
335        state.current_frame = 3;
336        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
337        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('X'));
338    }
339
340    #[test]
341    fn render_with_label() {
342        let frames: &[&str] = &["*"];
343        let spinner = Spinner::new().frames(frames).label("Go");
344        let area = Rect::new(0, 0, 10, 1);
345        let mut pool = GraphemePool::new();
346        let mut frame = Frame::new(10, 1, &mut pool);
347        let mut state = SpinnerState::default();
348        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
349
350        // "*" at x=0, then space, then "Go" at x=2
351        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('*'));
352        assert_eq!(cell_char(&frame.buffer, 2, 0), Some('G'));
353        assert_eq!(cell_char(&frame.buffer, 3, 0), Some('o'));
354    }
355
356    #[test]
357    fn render_with_block() {
358        let frames: &[&str] = &["!"];
359        let spinner = Spinner::new().frames(frames).block(Block::bordered());
360        // Block::bordered() includes 1 cell padding on each side, so we need
361        // at least 5 rows to have a 1-row inner content area.
362        let area = Rect::new(0, 0, 10, 5);
363        let mut pool = GraphemePool::new();
364        let mut frame = Frame::new(10, 5, &mut pool);
365        let mut state = SpinnerState::default();
366        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
367
368        // Inside the border + padding at (2, 2)
369        assert_eq!(cell_char(&frame.buffer, 2, 2), Some('!'));
370    }
371
372    #[test]
373    fn render_line_frames() {
374        let spinner = Spinner::new().frames(LINE);
375        let area = Rect::new(0, 0, 5, 1);
376
377        let mut pool = GraphemePool::new();
378        let mut frame = Frame::new(5, 1, &mut pool);
379        let mut state = SpinnerState { current_frame: 0 };
380        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
381        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('|'));
382
383        let mut pool = GraphemePool::new();
384        let mut frame = Frame::new(5, 1, &mut pool);
385        state.current_frame = 1;
386        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
387        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('/'));
388    }
389
390    #[test]
391    fn large_frame_index_wraps_correctly() {
392        let frames: &[&str] = &["A", "B"];
393        let spinner = Spinner::new().frames(frames);
394        let area = Rect::new(0, 0, 5, 1);
395        let mut pool = GraphemePool::new();
396        let mut frame = Frame::new(5, 1, &mut pool);
397        let mut state = SpinnerState {
398            current_frame: 1000,
399        };
400        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
401        // 1000 % 2 = 0 -> "A"
402        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('A'));
403    }
404
405    #[test]
406    fn dots_frame_set_has_expected_length() {
407        assert_eq!(DOTS.len(), 10);
408    }
409
410    #[test]
411    fn line_frame_set_has_expected_length() {
412        assert_eq!(LINE.len(), 4);
413    }
414
415    // --- Degradation tests ---
416
417    #[test]
418    fn degradation_skeleton_skips_entirely() {
419        use ftui_render::budget::DegradationLevel;
420
421        let frames: &[&str] = &["*"];
422        let spinner = Spinner::new().frames(frames).label("Loading");
423        let area = Rect::new(0, 0, 10, 1);
424        let mut pool = GraphemePool::new();
425        let mut frame = Frame::new(10, 1, &mut pool);
426        let mut state = SpinnerState::default();
427        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
428
429        frame.buffer.degradation = DegradationLevel::Skeleton;
430        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
431
432        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "          ");
433    }
434
435    #[test]
436    fn degradation_essential_only_shows_label_only() {
437        use ftui_render::budget::DegradationLevel;
438
439        let frames: &[&str] = &["*"];
440        let spinner = Spinner::new().frames(frames).label("Go");
441        let area = Rect::new(0, 0, 10, 1);
442        let mut pool = GraphemePool::new();
443        let mut frame = Frame::new(10, 1, &mut pool);
444        frame.buffer.degradation = DegradationLevel::EssentialOnly;
445        let mut state = SpinnerState::default();
446        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
447
448        // Label "Go" rendered, no spinner frame
449        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('G'));
450        assert_eq!(cell_char(&frame.buffer, 1, 0), Some('o'));
451    }
452
453    #[test]
454    fn degradation_simple_borders_uses_ascii_fallback() {
455        use ftui_render::budget::DegradationLevel;
456
457        // Use Unicode frames that should fall back to ASCII
458        let spinner = Spinner::new(); // default DOTS frames are Unicode
459        let area = Rect::new(0, 0, 5, 1);
460        let mut pool = GraphemePool::new();
461        let mut frame = Frame::new(5, 1, &mut pool);
462        frame.buffer.degradation = DegradationLevel::SimpleBorders;
463        let mut state = SpinnerState::default();
464        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
465
466        // Should use "*" fallback since DOTS are non-ASCII
467        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('*'));
468    }
469
470    #[test]
471    fn degradation_full_uses_unicode_frames() {
472        use ftui_render::budget::DegradationLevel;
473
474        let spinner = Spinner::new(); // DOTS frames
475        let area = Rect::new(0, 0, 5, 1);
476        let mut pool = GraphemePool::new();
477        let mut frame = Frame::new(5, 1, &mut pool);
478        frame.buffer.degradation = DegradationLevel::Full;
479        let mut state = SpinnerState::default();
480        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
481
482        // Should use the first DOTS frame '⠋'
483        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('⠋'));
484    }
485
486    #[test]
487    fn degradation_ascii_fallback_prefers_available_ascii_frame() {
488        use ftui_render::budget::DegradationLevel;
489
490        let frames: &[&str] = &["⠋", "-", "\\"];
491        let spinner = Spinner::new().frames(frames);
492        let area = Rect::new(0, 0, 5, 1);
493        let mut pool = GraphemePool::new();
494        let mut frame = Frame::new(5, 1, &mut pool);
495        frame.buffer.degradation = DegradationLevel::SimpleBorders;
496        let mut state = SpinnerState { current_frame: 0 };
497        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
498
499        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('-'));
500    }
501
502    #[test]
503    fn empty_frames_still_render_label() {
504        let frames: &[&str] = &[];
505        let spinner = Spinner::new().frames(frames).label("Loading");
506        let area = Rect::new(0, 0, 10, 1);
507        let mut pool = GraphemePool::new();
508        let mut frame = Frame::new(10, 1, &mut pool);
509        let mut state = SpinnerState::default();
510        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
511
512        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('L'));
513        assert_eq!(cell_char(&frame.buffer, 1, 0), Some('o'));
514    }
515
516    #[test]
517    fn render_shorter_label_clears_stale_suffix() {
518        let frames: &[&str] = &["*"];
519        let area = Rect::new(0, 0, 10, 1);
520        let mut pool = GraphemePool::new();
521        let mut frame = Frame::new(10, 1, &mut pool);
522        let mut state = SpinnerState::default();
523
524        StatefulWidget::render(
525            &Spinner::new().frames(frames).label("Loading"),
526            area,
527            &mut frame,
528            &mut state,
529        );
530        StatefulWidget::render(
531            &Spinner::new().frames(frames).label("Go"),
532            area,
533            &mut frame,
534            &mut state,
535        );
536
537        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "* Go      ");
538    }
539
540    #[test]
541    fn degradation_essential_only_clears_previous_spinner_frame() {
542        use ftui_render::budget::DegradationLevel;
543
544        let frames: &[&str] = &["*"];
545        let spinner = Spinner::new().frames(frames).label("Go");
546        let area = Rect::new(0, 0, 10, 1);
547        let mut pool = GraphemePool::new();
548        let mut frame = Frame::new(10, 1, &mut pool);
549        let mut state = SpinnerState::default();
550
551        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
552        frame.buffer.degradation = DegradationLevel::EssentialOnly;
553        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
554
555        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "Go        ");
556    }
557}