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() && !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 if !deg.render_content() {
128 clear_text_area(frame, area, Style::default());
129 return;
130 }
131
132 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 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
190impl 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 #[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 #[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 #[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 }
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 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 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 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 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 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 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 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 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 #[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 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 let spinner = Spinner::new(); 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 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(); 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 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}