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        if frame.a11y_enabled() {
107            frame.push_a11y_nodes(ftui_a11y::Accessible::accessibility_nodes(self, area));
108        }
109        #[cfg(feature = "tracing")]
110        let _span = tracing::debug_span!(
111            "widget_render",
112            widget = "Spinner",
113            x = area.x,
114            y = area.y,
115            w = area.width,
116            h = area.height
117        )
118        .entered();
119
120        let deg = frame.buffer.degradation;
121
122        // Skeleton+: skip entirely (spinner is decorative)
123        if !deg.render_content() {
124            clear_text_area(frame, area, Style::default());
125            return;
126        }
127
128        // EssentialOnly: spinner is decorative, only show label text
129        if !deg.render_decorative() {
130            clear_text_area(frame, area, Style::default());
131            if let Some(label) = self.label {
132                crate::draw_text_span(frame, area.x, area.y, label, Style::default(), area.right());
133            }
134            return;
135        }
136
137        let style = if deg.apply_styling() {
138            self.style
139        } else {
140            Style::default()
141        };
142
143        clear_text_area(frame, area, style);
144
145        let spinner_area = match &self.block {
146            Some(b) => {
147                b.render(area, frame);
148                b.inner(area)
149            }
150            None => area,
151        };
152
153        if spinner_area.is_empty() {
154            return;
155        }
156
157        let mut x = spinner_area.left();
158        let y = spinner_area.top();
159        if let Some(frame_char) =
160            self.frame_for_render(state.current_frame, deg.use_unicode_borders())
161        {
162            crate::draw_text_span(frame, x, y, frame_char, style, spinner_area.right());
163            let w = display_width(frame_char);
164            x += w as u16;
165        }
166
167        // Render label
168        if let Some(label) = self.label {
169            if x > spinner_area.left() {
170                x += 1;
171            }
172            if x < spinner_area.right() {
173                crate::draw_text_span(frame, x, y, label, style, spinner_area.right());
174            }
175        }
176    }
177}
178
179impl<'a> Widget for Spinner<'a> {
180    fn render(&self, area: Rect, frame: &mut Frame) {
181        let mut state = SpinnerState::default();
182        StatefulWidget::render(self, area, frame, &mut state);
183    }
184}
185
186// ============================================================================
187// Accessibility
188// ============================================================================
189
190impl ftui_a11y::Accessible for Spinner<'_> {
191    fn accessibility_nodes(&self, area: Rect) -> Vec<ftui_a11y::node::A11yNodeInfo> {
192        use ftui_a11y::node::{A11yNodeInfo, A11yRole, A11yState};
193
194        let id = crate::a11y_node_id(area);
195        let name = self
196            .label
197            .map(|l| format!("Loading: {l}"))
198            .unwrap_or_else(|| "Loading...".to_owned());
199        let node = A11yNodeInfo::new(id, A11yRole::ProgressBar, area)
200            .with_name(name)
201            .with_state(A11yState {
202                busy: true,
203                ..A11yState::default()
204            });
205        vec![node]
206    }
207}
208
209#[cfg(test)]
210mod tests {
211    use super::*;
212    use ftui_render::buffer::Buffer;
213    use ftui_render::grapheme_pool::GraphemePool;
214
215    fn cell_char(buf: &Buffer, x: u16, y: u16) -> Option<char> {
216        buf.get(x, y).and_then(|c| c.content.as_char())
217    }
218
219    fn raw_row_text(buf: &Buffer, y: u16, width: u16) -> String {
220        (0..width)
221            .map(|x| {
222                buf.get(x, y)
223                    .and_then(|c| c.content.as_char())
224                    .unwrap_or(' ')
225            })
226            .collect()
227    }
228
229    // --- SpinnerState tests ---
230
231    #[test]
232    fn state_default() {
233        let state = SpinnerState::default();
234        assert_eq!(state.current_frame, 0);
235    }
236
237    #[test]
238    fn state_tick_increments() {
239        let mut state = SpinnerState::default();
240        state.tick();
241        assert_eq!(state.current_frame, 1);
242        state.tick();
243        assert_eq!(state.current_frame, 2);
244    }
245
246    #[test]
247    fn state_tick_wraps_on_overflow() {
248        let mut state = SpinnerState {
249            current_frame: usize::MAX,
250        };
251        state.tick();
252        assert_eq!(state.current_frame, 0);
253    }
254
255    // --- Builder tests ---
256
257    #[test]
258    fn default_uses_dots_frames() {
259        let spinner = Spinner::new();
260        assert_eq!(spinner.frames.len(), DOTS.len());
261        assert_eq!(spinner.frames, DOTS);
262    }
263
264    #[test]
265    fn custom_frames() {
266        let frames: &[&str] = &["A", "B", "C"];
267        let spinner = Spinner::new().frames(frames);
268        assert_eq!(spinner.frames.len(), 3);
269    }
270
271    #[test]
272    fn builder_label() {
273        let spinner = Spinner::new().label("Loading...");
274        assert_eq!(spinner.label, Some("Loading..."));
275    }
276
277    // --- Rendering tests ---
278
279    #[test]
280    fn render_zero_area() {
281        let spinner = Spinner::new();
282        let area = Rect::new(0, 0, 0, 0);
283        let mut pool = GraphemePool::new();
284        let mut frame = Frame::new(1, 1, &mut pool);
285        Widget::render(&spinner, area, &mut frame);
286        // Should not panic
287    }
288
289    #[test]
290    fn stateless_render_uses_frame_zero() {
291        let frames: &[&str] = &["A", "B", "C"];
292        let spinner = Spinner::new().frames(frames);
293        let area = Rect::new(0, 0, 5, 1);
294        let mut pool = GraphemePool::new();
295        let mut frame = Frame::new(5, 1, &mut pool);
296        Widget::render(&spinner, area, &mut frame);
297
298        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('A'));
299    }
300
301    #[test]
302    fn stateful_render_cycles_frames() {
303        let frames: &[&str] = &["X", "Y", "Z"];
304        let spinner = Spinner::new().frames(frames);
305        let area = Rect::new(0, 0, 5, 1);
306
307        // Frame 0 -> "X"
308        let mut pool = GraphemePool::new();
309        let mut frame = Frame::new(5, 1, &mut pool);
310        let mut state = SpinnerState { current_frame: 0 };
311        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
312        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('X'));
313
314        // Frame 1 -> "Y"
315        let mut pool = GraphemePool::new();
316        let mut frame = Frame::new(5, 1, &mut pool);
317        state.current_frame = 1;
318        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
319        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('Y'));
320
321        // Frame 2 -> "Z"
322        let mut pool = GraphemePool::new();
323        let mut frame = Frame::new(5, 1, &mut pool);
324        state.current_frame = 2;
325        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
326        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('Z'));
327
328        // Frame 3 wraps -> "X"
329        let mut pool = GraphemePool::new();
330        let mut frame = Frame::new(5, 1, &mut pool);
331        state.current_frame = 3;
332        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
333        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('X'));
334    }
335
336    #[test]
337    fn render_with_label() {
338        let frames: &[&str] = &["*"];
339        let spinner = Spinner::new().frames(frames).label("Go");
340        let area = Rect::new(0, 0, 10, 1);
341        let mut pool = GraphemePool::new();
342        let mut frame = Frame::new(10, 1, &mut pool);
343        let mut state = SpinnerState::default();
344        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
345
346        // "*" at x=0, then space, then "Go" at x=2
347        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('*'));
348        assert_eq!(cell_char(&frame.buffer, 2, 0), Some('G'));
349        assert_eq!(cell_char(&frame.buffer, 3, 0), Some('o'));
350    }
351
352    #[test]
353    fn render_with_block() {
354        let frames: &[&str] = &["!"];
355        let spinner = Spinner::new().frames(frames).block(Block::bordered());
356        // Block::bordered() includes 1 cell padding on each side, so we need
357        // at least 5 rows to have a 1-row inner content area.
358        let area = Rect::new(0, 0, 10, 5);
359        let mut pool = GraphemePool::new();
360        let mut frame = Frame::new(10, 5, &mut pool);
361        let mut state = SpinnerState::default();
362        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
363
364        // Inside the border + padding at (2, 2)
365        assert_eq!(cell_char(&frame.buffer, 2, 2), Some('!'));
366    }
367
368    #[test]
369    fn render_line_frames() {
370        let spinner = Spinner::new().frames(LINE);
371        let area = Rect::new(0, 0, 5, 1);
372
373        let mut pool = GraphemePool::new();
374        let mut frame = Frame::new(5, 1, &mut pool);
375        let mut state = SpinnerState { current_frame: 0 };
376        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
377        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('|'));
378
379        let mut pool = GraphemePool::new();
380        let mut frame = Frame::new(5, 1, &mut pool);
381        state.current_frame = 1;
382        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
383        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('/'));
384    }
385
386    #[test]
387    fn large_frame_index_wraps_correctly() {
388        let frames: &[&str] = &["A", "B"];
389        let spinner = Spinner::new().frames(frames);
390        let area = Rect::new(0, 0, 5, 1);
391        let mut pool = GraphemePool::new();
392        let mut frame = Frame::new(5, 1, &mut pool);
393        let mut state = SpinnerState {
394            current_frame: 1000,
395        };
396        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
397        // 1000 % 2 = 0 -> "A"
398        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('A'));
399    }
400
401    #[test]
402    fn dots_frame_set_has_expected_length() {
403        assert_eq!(DOTS.len(), 10);
404    }
405
406    #[test]
407    fn line_frame_set_has_expected_length() {
408        assert_eq!(LINE.len(), 4);
409    }
410
411    // --- Degradation tests ---
412
413    #[test]
414    fn degradation_skeleton_skips_entirely() {
415        use ftui_render::budget::DegradationLevel;
416
417        let frames: &[&str] = &["*"];
418        let spinner = Spinner::new().frames(frames).label("Loading");
419        let area = Rect::new(0, 0, 10, 1);
420        let mut pool = GraphemePool::new();
421        let mut frame = Frame::new(10, 1, &mut pool);
422        let mut state = SpinnerState::default();
423        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
424
425        frame.buffer.degradation = DegradationLevel::Skeleton;
426        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
427
428        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "          ");
429    }
430
431    #[test]
432    fn degradation_essential_only_shows_label_only() {
433        use ftui_render::budget::DegradationLevel;
434
435        let frames: &[&str] = &["*"];
436        let spinner = Spinner::new().frames(frames).label("Go");
437        let area = Rect::new(0, 0, 10, 1);
438        let mut pool = GraphemePool::new();
439        let mut frame = Frame::new(10, 1, &mut pool);
440        frame.buffer.degradation = DegradationLevel::EssentialOnly;
441        let mut state = SpinnerState::default();
442        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
443
444        // Label "Go" rendered, no spinner frame
445        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('G'));
446        assert_eq!(cell_char(&frame.buffer, 1, 0), Some('o'));
447    }
448
449    #[test]
450    fn degradation_simple_borders_uses_ascii_fallback() {
451        use ftui_render::budget::DegradationLevel;
452
453        // Use Unicode frames that should fall back to ASCII
454        let spinner = Spinner::new(); // default DOTS frames are Unicode
455        let area = Rect::new(0, 0, 5, 1);
456        let mut pool = GraphemePool::new();
457        let mut frame = Frame::new(5, 1, &mut pool);
458        frame.buffer.degradation = DegradationLevel::SimpleBorders;
459        let mut state = SpinnerState::default();
460        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
461
462        // Should use "*" fallback since DOTS are non-ASCII
463        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('*'));
464    }
465
466    #[test]
467    fn degradation_full_uses_unicode_frames() {
468        use ftui_render::budget::DegradationLevel;
469
470        let spinner = Spinner::new(); // DOTS frames
471        let area = Rect::new(0, 0, 5, 1);
472        let mut pool = GraphemePool::new();
473        let mut frame = Frame::new(5, 1, &mut pool);
474        frame.buffer.degradation = DegradationLevel::Full;
475        let mut state = SpinnerState::default();
476        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
477
478        // Should use the first DOTS frame '⠋'
479        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('⠋'));
480    }
481
482    #[test]
483    fn degradation_ascii_fallback_prefers_available_ascii_frame() {
484        use ftui_render::budget::DegradationLevel;
485
486        let frames: &[&str] = &["⠋", "-", "\\"];
487        let spinner = Spinner::new().frames(frames);
488        let area = Rect::new(0, 0, 5, 1);
489        let mut pool = GraphemePool::new();
490        let mut frame = Frame::new(5, 1, &mut pool);
491        frame.buffer.degradation = DegradationLevel::SimpleBorders;
492        let mut state = SpinnerState { current_frame: 0 };
493        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
494
495        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('-'));
496    }
497
498    #[test]
499    fn empty_frames_still_render_label() {
500        let frames: &[&str] = &[];
501        let spinner = Spinner::new().frames(frames).label("Loading");
502        let area = Rect::new(0, 0, 10, 1);
503        let mut pool = GraphemePool::new();
504        let mut frame = Frame::new(10, 1, &mut pool);
505        let mut state = SpinnerState::default();
506        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
507
508        assert_eq!(cell_char(&frame.buffer, 0, 0), Some('L'));
509        assert_eq!(cell_char(&frame.buffer, 1, 0), Some('o'));
510    }
511
512    #[test]
513    fn render_shorter_label_clears_stale_suffix() {
514        let frames: &[&str] = &["*"];
515        let area = Rect::new(0, 0, 10, 1);
516        let mut pool = GraphemePool::new();
517        let mut frame = Frame::new(10, 1, &mut pool);
518        let mut state = SpinnerState::default();
519
520        StatefulWidget::render(
521            &Spinner::new().frames(frames).label("Loading"),
522            area,
523            &mut frame,
524            &mut state,
525        );
526        StatefulWidget::render(
527            &Spinner::new().frames(frames).label("Go"),
528            area,
529            &mut frame,
530            &mut state,
531        );
532
533        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "* Go      ");
534    }
535
536    #[test]
537    fn degradation_essential_only_clears_previous_spinner_frame() {
538        use ftui_render::budget::DegradationLevel;
539
540        let frames: &[&str] = &["*"];
541        let spinner = Spinner::new().frames(frames).label("Go");
542        let area = Rect::new(0, 0, 10, 1);
543        let mut pool = GraphemePool::new();
544        let mut frame = Frame::new(10, 1, &mut pool);
545        let mut state = SpinnerState::default();
546
547        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
548        frame.buffer.degradation = DegradationLevel::EssentialOnly;
549        StatefulWidget::render(&spinner, area, &mut frame, &mut state);
550
551        assert_eq!(raw_row_text(&frame.buffer, 0, 10), "Go        ");
552    }
553}