1#![forbid(unsafe_code)]
2
3use 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
12pub const DOTS: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
14pub const LINE: &[&str] = &["|", "/", "-", "\\"];
16
17#[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 pub fn new() -> Self {
29 Self {
30 block: None,
31 style: Style::default(),
32 frames: DOTS,
33 label: None,
34 }
35 }
36
37 #[must_use]
39 pub fn block(mut self, block: Block<'a>) -> Self {
40 self.block = Some(block);
41 self
42 }
43
44 #[must_use]
46 pub fn style(mut self, style: Style) -> Self {
47 self.style = style;
48 self
49 }
50
51 #[must_use]
53 pub fn frames(mut self, frames: &'a [&'a str]) -> Self {
54 self.frames = frames;
55 self
56 }
57
58 #[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#[derive(Debug, Clone, Default)]
90pub struct SpinnerState {
91 pub current_frame: usize,
93}
94
95impl SpinnerState {
96 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 if !deg.render_content() {
124 clear_text_area(frame, area, Style::default());
125 return;
126 }
127
128 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 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
186impl 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 #[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 #[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 #[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 }
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 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 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 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 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 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 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 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 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 #[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 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 let spinner = Spinner::new(); 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 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(); 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 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}