Skip to main content

ftui_widgets/
scrollbar.rs

1#![forbid(unsafe_code)]
2
3//! Scrollbar widget.
4//!
5//! A widget to display a scrollbar.
6
7use crate::mouse::MouseResult;
8use crate::{StatefulWidget, Widget, clear_text_area, draw_text_span};
9use ftui_core::event::{MouseButton, MouseEvent, MouseEventKind};
10use ftui_core::geometry::Rect;
11use ftui_render::frame::{Frame, HitId, HitRegion};
12use ftui_style::Style;
13use ftui_text::display_width;
14
15/// Scrollbar orientation.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
17pub enum ScrollbarOrientation {
18    /// Vertical scrollbar on the right side.
19    #[default]
20    VerticalRight,
21    /// Vertical scrollbar on the left side.
22    VerticalLeft,
23    /// Horizontal scrollbar on the bottom.
24    HorizontalBottom,
25    /// Horizontal scrollbar on the top.
26    HorizontalTop,
27}
28
29/// Hit data part for track (background).
30pub const SCROLLBAR_PART_TRACK: u64 = 0;
31/// Hit data part for thumb (draggable).
32pub const SCROLLBAR_PART_THUMB: u64 = 1;
33/// Hit data part for begin button (up/left).
34pub const SCROLLBAR_PART_BEGIN: u64 = 2;
35/// Hit data part for end button (down/right).
36pub const SCROLLBAR_PART_END: u64 = 3;
37
38/// A widget to display a scrollbar.
39#[derive(Debug, Clone, Default)]
40pub struct Scrollbar<'a> {
41    orientation: ScrollbarOrientation,
42    thumb_style: Style,
43    track_style: Style,
44    begin_symbol: Option<&'a str>,
45    end_symbol: Option<&'a str>,
46    track_symbol: Option<&'a str>,
47    thumb_symbol: Option<&'a str>,
48    hit_id: Option<HitId>,
49}
50
51impl<'a> Scrollbar<'a> {
52    /// Create a new scrollbar with the given orientation.
53    #[must_use]
54    pub fn new(orientation: ScrollbarOrientation) -> Self {
55        Self {
56            orientation,
57            thumb_style: Style::default(),
58            track_style: Style::default(),
59            begin_symbol: None,
60            end_symbol: None,
61            track_symbol: None,
62            thumb_symbol: None,
63            hit_id: None,
64        }
65    }
66
67    /// Set the style for the thumb (draggable indicator).
68    #[must_use]
69    pub fn thumb_style(mut self, style: Style) -> Self {
70        self.thumb_style = style;
71        self
72    }
73
74    /// Set the style for the track background.
75    #[must_use]
76    pub fn track_style(mut self, style: Style) -> Self {
77        self.track_style = style;
78        self
79    }
80
81    /// Set custom symbols for track, thumb, begin, and end markers.
82    #[must_use]
83    pub fn symbols(
84        mut self,
85        track: &'a str,
86        thumb: &'a str,
87        begin: Option<&'a str>,
88        end: Option<&'a str>,
89    ) -> Self {
90        self.track_symbol = Some(track);
91        self.thumb_symbol = Some(thumb);
92        self.begin_symbol = begin;
93        self.end_symbol = end;
94        self
95    }
96
97    /// Set a hit ID for mouse interaction.
98    #[must_use]
99    pub fn hit_id(mut self, id: HitId) -> Self {
100        self.hit_id = Some(id);
101        self
102    }
103}
104
105/// Mutable state for a [`Scrollbar`] widget.
106#[derive(Debug, Clone, Default)]
107pub struct ScrollbarState {
108    /// Total number of scrollable content units.
109    pub content_length: usize,
110    /// Current scroll position within the content.
111    pub position: usize,
112    /// Number of content units visible in the viewport.
113    pub viewport_length: usize,
114    /// Drag anchor point (offset from thumb top) to prevent jumping.
115    pub drag_anchor: Option<usize>,
116    /// Cache of the track geometry for hit-testing fallback during drag.
117    track_layout: Option<TrackLayout>,
118}
119
120#[derive(Debug, Clone, Copy)]
121struct TrackLayout {
122    rect: Rect,
123    is_vertical: bool,
124}
125
126impl ScrollbarState {
127    /// Create a new scrollbar state with given content, position, and viewport sizes.
128    #[must_use]
129    pub fn new(content_length: usize, position: usize, viewport_length: usize) -> Self {
130        Self {
131            content_length,
132            position,
133            viewport_length,
134            drag_anchor: None,
135            track_layout: None,
136        }
137    }
138
139    /// Calculate thumb offset and size for a given track length.
140    fn calc_thumb_geometry(&self, track_len: usize) -> (usize, usize) {
141        if track_len == 0 {
142            return (0, 0);
143        }
144        if self.content_length == 0 {
145            return (0, track_len);
146        }
147
148        let viewport_ratio = self.viewport_length as f64 / self.content_length as f64;
149        let thumb_size = (track_len as f64 * viewport_ratio).max(1.0).round() as usize;
150        let thumb_size = thumb_size.min(track_len);
151
152        let max_pos = self.content_length.saturating_sub(self.viewport_length);
153        let pos_ratio = if max_pos == 0 {
154            0.0
155        } else {
156            self.position.min(max_pos) as f64 / max_pos as f64
157        };
158
159        let available_track = track_len.saturating_sub(thumb_size);
160        let thumb_offset = (available_track as f64 * pos_ratio).round() as usize;
161
162        (thumb_offset, thumb_size)
163    }
164
165    /// Handle a mouse event for this scrollbar.
166    ///
167    /// # Hit data convention
168    ///
169    /// The hit data (`u64`) is encoded as:
170    /// `[8: part] [28: track_len] [28: track_pos]`
171    ///
172    /// - `part`: One of `SCROLLBAR_PART_*`.
173    /// - `track_len`: The effective length of the track (excluding buttons).
174    /// - `track_pos`: The position within the effective track (0-based).
175    ///
176    /// # Arguments
177    ///
178    /// * `event` — the mouse event from the terminal
179    /// * `hit` — result of `frame.hit_test(event.x, event.y)`, if available
180    /// * `expected_id` — the `HitId` this scrollbar was rendered with
181    pub fn handle_mouse(
182        &mut self,
183        event: &MouseEvent,
184        hit: Option<(HitId, HitRegion, u64)>,
185        expected_id: HitId,
186    ) -> MouseResult {
187        match event.kind {
188            MouseEventKind::Down(MouseButton::Left) => {
189                if let Some((id, HitRegion::Scrollbar, data)) = hit
190                    && id == expected_id
191                {
192                    let part = data >> 56;
193                    match part {
194                        SCROLLBAR_PART_BEGIN => {
195                            self.scroll_up(1);
196                            return MouseResult::Scrolled;
197                        }
198                        SCROLLBAR_PART_END => {
199                            self.scroll_down(1);
200                            return MouseResult::Scrolled;
201                        }
202                        SCROLLBAR_PART_THUMB => {
203                            let track_len = ((data >> 28) & 0x0FFF_FFFF) as usize;
204                            let track_pos = (data & 0x0FFF_FFFF) as usize;
205                            let (thumb_offset, _) = self.calc_thumb_geometry(track_len);
206                            // Store where we grabbed the thumb (relative to thumb top)
207                            self.drag_anchor = Some(track_pos.saturating_sub(thumb_offset));
208                            // Prevent event bubbling by returning Scrolled
209                            return MouseResult::Scrolled;
210                        }
211                        SCROLLBAR_PART_TRACK => {
212                            let track_len = ((data >> 28) & 0x0FFF_FFFF) as usize;
213                            let track_pos = (data & 0x0FFF_FFFF) as usize;
214                            if track_len == 0 {
215                                return MouseResult::Ignored;
216                            }
217
218                            // Unify track click with drag logic: center the thumb on the click.
219                            let (_, thumb_size) = self.calc_thumb_geometry(track_len);
220                            let available = track_len.saturating_sub(thumb_size);
221                            let denom = available.max(1);
222
223                            let target_thumb_top = track_pos.saturating_sub(thumb_size / 2);
224                            let clamped_top = target_thumb_top.min(denom);
225
226                            let max_pos = self.content_length.saturating_sub(self.viewport_length);
227                            self.position = if max_pos == 0 {
228                                0
229                            } else {
230                                let num = (clamped_top as u128) * (max_pos as u128);
231                                let pos = (num + (denom as u128 / 2)) / denom as u128;
232                                pos as usize
233                            };
234
235                            // Update drag anchor to match the new thumb position immediately,
236                            // preventing a jump if the user drags after clicking the track.
237                            let (thumb_offset, _) = self.calc_thumb_geometry(track_len);
238                            self.drag_anchor = Some(track_pos.saturating_sub(thumb_offset));
239
240                            return MouseResult::Scrolled;
241                        }
242                        _ => {}
243                    }
244                }
245                MouseResult::Ignored
246            }
247            MouseEventKind::Drag(MouseButton::Left) => {
248                // Determine track length and mouse position relative to track.
249                // 1. Try Hit data (accurate for wide chars, complex layouts).
250                // 2. Fallback to cached layout (if dragging outside component).
251                let hit_data = if let Some((id, HitRegion::Scrollbar, data)) = hit
252                    && id == expected_id
253                {
254                    let part = data >> 56;
255                    if matches!(part, SCROLLBAR_PART_TRACK | SCROLLBAR_PART_THUMB) {
256                        let len = ((data >> 28) & 0x0FFF_FFFF) as usize;
257                        let pos = (data & 0x0FFF_FFFF) as usize;
258                        Some((len, pos))
259                    } else {
260                        None
261                    }
262                } else {
263                    None
264                };
265
266                let (track_len, track_pos) = if let Some((len, pos)) = hit_data {
267                    (len, pos)
268                } else if self.drag_anchor.is_some()
269                    && let Some(layout) = self.track_layout
270                {
271                    // Fallback: calculate from mouse event relative to track rect
272                    let rel = if layout.is_vertical {
273                        event.y.saturating_sub(layout.rect.y)
274                    } else {
275                        event.x.saturating_sub(layout.rect.x)
276                    };
277                    let len = if layout.is_vertical {
278                        layout.rect.height as usize
279                    } else {
280                        layout.rect.width as usize
281                    };
282                    let pos = rel.min(len.saturating_sub(1) as u16) as usize;
283                    (len, pos)
284                } else {
285                    return MouseResult::Ignored;
286                };
287
288                if track_len == 0 {
289                    return MouseResult::Ignored;
290                }
291
292                let (_, thumb_size) = self.calc_thumb_geometry(track_len);
293                let available = track_len.saturating_sub(thumb_size);
294                let denom = available.max(1);
295
296                // If we have an anchor, align that point on thumb to mouse.
297                // Otherwise (drag started outside thumb?), center it or use raw pos.
298                let anchor = self.drag_anchor.unwrap_or(thumb_size / 2);
299
300                // Desired top of thumb
301                let target_thumb_top = track_pos.saturating_sub(anchor);
302                let clamped_top = target_thumb_top.min(denom);
303
304                let max_pos = self.content_length.saturating_sub(self.viewport_length);
305                self.position = if max_pos == 0 {
306                    0
307                } else {
308                    // Map thumb top range [0, available] to content range [0, max_pos]
309                    let num = (clamped_top as u128) * (max_pos as u128);
310                    // Round to nearest
311                    let pos = (num + (denom as u128 / 2)) / denom as u128;
312                    pos as usize
313                };
314                MouseResult::Scrolled
315            }
316            MouseEventKind::Up(MouseButton::Left) => {
317                let was_dragging = self.drag_anchor.take().is_some();
318                if was_dragging {
319                    MouseResult::Scrolled
320                } else {
321                    MouseResult::Ignored
322                }
323            }
324            MouseEventKind::ScrollUp => {
325                self.scroll_up(3);
326                MouseResult::Scrolled
327            }
328            MouseEventKind::ScrollDown => {
329                self.scroll_down(3);
330                MouseResult::Scrolled
331            }
332            _ => MouseResult::Ignored,
333        }
334    }
335
336    /// Scroll the content up by the given number of lines.
337    pub fn scroll_up(&mut self, lines: usize) {
338        self.position = self.position.saturating_sub(lines);
339    }
340
341    /// Scroll the content down by the given number of lines.
342    ///
343    /// Clamps so that the viewport stays within content bounds.
344    pub fn scroll_down(&mut self, lines: usize) {
345        let max_pos = self.content_length.saturating_sub(self.viewport_length);
346        self.position = self.position.saturating_add(lines).min(max_pos);
347    }
348}
349
350impl<'a> StatefulWidget for Scrollbar<'a> {
351    type State = ScrollbarState;
352
353    fn render(&self, area: Rect, frame: &mut Frame, state: &mut Self::State) {
354        if frame.a11y_enabled() {
355            frame.push_a11y_nodes(ftui_a11y::Accessible::accessibility_nodes(self, area));
356        }
357        #[cfg(feature = "tracing")]
358        let _span = tracing::debug_span!(
359            "widget_render",
360            widget = "Scrollbar",
361            x = area.x,
362            y = area.y,
363            w = area.width,
364            h = area.height
365        )
366        .entered();
367
368        // Scrollbar is decorative — skip at EssentialOnly+
369        if !frame.buffer.degradation.render_decorative() {
370            state.track_layout = None;
371            clear_text_area(frame, area, Style::default());
372            return;
373        }
374
375        if area.is_empty() || state.content_length == 0 {
376            state.track_layout = None;
377            clear_text_area(frame, area, Style::default());
378            return;
379        }
380
381        let is_vertical = match self.orientation {
382            ScrollbarOrientation::VerticalRight | ScrollbarOrientation::VerticalLeft => true,
383            ScrollbarOrientation::HorizontalBottom | ScrollbarOrientation::HorizontalTop => false,
384        };
385
386        let length = if is_vertical { area.height } else { area.width } as usize;
387        if length == 0 {
388            state.track_layout = None;
389            return;
390        }
391
392        // Calculate layout
393        let start_offset = if let Some(s) = self.begin_symbol {
394            if is_vertical { 1 } else { display_width(s) }
395        } else {
396            0
397        };
398        let end_offset = if let Some(s) = self.end_symbol {
399            if is_vertical { 1 } else { display_width(s) }
400        } else {
401            0
402        };
403
404        // Effective track excludes buttons
405        let track_len = length.saturating_sub(start_offset + end_offset);
406
407        // Calculate thumb size and position within the effective track
408        let (thumb_offset, thumb_size) = state.calc_thumb_geometry(track_len);
409
410        // Symbols
411        let track_char = self
412            .track_symbol
413            .unwrap_or(if is_vertical { "│" } else { "─" });
414        let thumb_char = self.thumb_symbol.unwrap_or("█");
415        let begin_char = self
416            .begin_symbol
417            .unwrap_or(if is_vertical { "▲" } else { "◄" });
418        let end_char = self
419            .end_symbol
420            .unwrap_or(if is_vertical { "▼" } else { "►" });
421
422        // Update track layout for mouse interaction fallback
423        let max_w = display_width(track_char)
424            .max(display_width(thumb_char))
425            .max(1);
426        let track_rect = if is_vertical {
427            let x = match self.orientation {
428                ScrollbarOrientation::VerticalRight => {
429                    area.right().saturating_sub(max_w as u16).max(area.left())
430                }
431                ScrollbarOrientation::VerticalLeft => area.left(),
432                _ => unreachable!(),
433            };
434            Rect::new(
435                x,
436                area.top().saturating_add(start_offset as u16),
437                max_w as u16,
438                track_len as u16,
439            )
440        } else {
441            let y = match self.orientation {
442                ScrollbarOrientation::HorizontalBottom => area.bottom().saturating_sub(1),
443                ScrollbarOrientation::HorizontalTop => area.top(),
444                _ => unreachable!(),
445            };
446            Rect::new(
447                area.left().saturating_add(start_offset as u16),
448                y,
449                track_len as u16,
450                1,
451            )
452        };
453        state.track_layout = Some(TrackLayout {
454            rect: track_rect,
455            is_vertical,
456        });
457
458        // Draw
459        let mut next_draw_index = 0;
460        for i in 0..length {
461            if i < next_draw_index {
462                continue;
463            }
464
465            // Determine part type and relative position
466            let (symbol, part, rel_pos) = if i < start_offset {
467                (begin_char, SCROLLBAR_PART_BEGIN, 0)
468            } else if i >= length.saturating_sub(end_offset) {
469                (end_char, SCROLLBAR_PART_END, 0)
470            } else {
471                let track_idx = i - start_offset;
472                let is_thumb = track_idx >= thumb_offset && track_idx < thumb_offset + thumb_size;
473                if is_thumb {
474                    (thumb_char, SCROLLBAR_PART_THUMB, track_idx)
475                } else {
476                    (track_char, SCROLLBAR_PART_TRACK, track_idx)
477                }
478            };
479
480            let symbol_width = display_width(symbol);
481            if is_vertical {
482                next_draw_index = i + 1;
483            } else {
484                next_draw_index = i + symbol_width;
485            }
486
487            let style = if !frame.buffer.degradation.apply_styling() {
488                Style::default()
489            } else if part == SCROLLBAR_PART_THUMB {
490                self.thumb_style
491            } else {
492                self.track_style
493            };
494
495            let (x, y) = if is_vertical {
496                let x = match self.orientation {
497                    ScrollbarOrientation::VerticalRight => area
498                        .right()
499                        .saturating_sub(symbol_width.max(1) as u16)
500                        .max(area.left()),
501                    ScrollbarOrientation::VerticalLeft => area.left(),
502                    _ => unreachable!(),
503                };
504                (x, area.top().saturating_add(i as u16))
505            } else {
506                let y = match self.orientation {
507                    ScrollbarOrientation::HorizontalBottom => area.bottom().saturating_sub(1),
508                    ScrollbarOrientation::HorizontalTop => area.top(),
509                    _ => unreachable!(),
510                };
511                (area.left().saturating_add(i as u16), y)
512            };
513
514            // Only draw if within bounds
515            if x < area.right() && y < area.bottom() {
516                draw_text_span(frame, x, y, symbol, style, area.right());
517
518                if let Some(id) = self.hit_id {
519                    // Encode data: [8: part] [28: track_len] [28: track_pos]
520                    let data = (part << 56)
521                        | ((track_len as u64 & 0x0FFF_FFFF) << 28)
522                        | (rel_pos as u64 & 0x0FFF_FFFF);
523
524                    let hit_w = (symbol_width.max(1) as u16).min(area.right().saturating_sub(x));
525                    frame.register_hit(Rect::new(x, y, hit_w, 1), id, HitRegion::Scrollbar, data);
526                }
527            }
528        }
529    }
530}
531
532impl<'a> Widget for Scrollbar<'a> {
533    fn render(&self, area: Rect, frame: &mut Frame) {
534        let mut state = ScrollbarState::default();
535        StatefulWidget::render(self, area, frame, &mut state);
536    }
537}
538
539// ============================================================================
540// Accessibility
541// ============================================================================
542
543impl ftui_a11y::Accessible for Scrollbar<'_> {
544    fn accessibility_nodes(&self, area: Rect) -> Vec<ftui_a11y::node::A11yNodeInfo> {
545        use ftui_a11y::node::{A11yNodeInfo, A11yRole, A11yState};
546
547        let id = crate::a11y_node_id(area);
548        let orientation = match self.orientation {
549            ScrollbarOrientation::VerticalRight | ScrollbarOrientation::VerticalLeft => "vertical",
550            ScrollbarOrientation::HorizontalBottom | ScrollbarOrientation::HorizontalTop => {
551                "horizontal"
552            }
553        };
554        let name = format!("{orientation} scrollbar");
555        let node = A11yNodeInfo::new(id, A11yRole::ScrollBar, area)
556            .with_name(name)
557            .with_state(A11yState {
558                // Scrollbars are always interactive but don't themselves hold focus;
559                // the viewport they scroll is the focusable element.
560                ..A11yState::default()
561            });
562        vec![node]
563    }
564}
565
566#[cfg(test)]
567mod tests {
568    use super::*;
569    use ftui_render::grapheme_pool::GraphemePool;
570
571    #[test]
572    fn scrollbar_empty_area() {
573        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
574        let area = Rect::new(0, 0, 0, 0);
575        let mut pool = GraphemePool::new();
576        let mut frame = Frame::new(1, 1, &mut pool);
577        let mut state = ScrollbarState::new(100, 0, 10);
578        StatefulWidget::render(&sb, area, &mut frame, &mut state);
579    }
580
581    #[test]
582    fn scrollbar_zero_content() {
583        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
584        let area = Rect::new(0, 0, 1, 10);
585        let mut pool = GraphemePool::new();
586        let mut frame = Frame::new(1, 10, &mut pool);
587        let mut state = ScrollbarState::new(100, 0, 10);
588        StatefulWidget::render(&sb, area, &mut frame, &mut state);
589
590        state.content_length = 0;
591        StatefulWidget::render(&sb, area, &mut frame, &mut state);
592
593        for y in 0..10u16 {
594            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
595        }
596        assert!(state.track_layout.is_none());
597    }
598
599    #[test]
600    fn scrollbar_vertical_right_renders() {
601        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
602        let area = Rect::new(0, 0, 1, 10);
603        let mut pool = GraphemePool::new();
604        let mut frame = Frame::new(1, 10, &mut pool);
605        let mut state = ScrollbarState::new(100, 0, 10);
606        StatefulWidget::render(&sb, area, &mut frame, &mut state);
607
608        // Thumb should be at the top (position=0), track should have chars
609        let top_cell = frame.buffer.get(0, 0).unwrap();
610        assert!(top_cell.content.as_char().is_some());
611    }
612
613    #[test]
614    fn scrollbar_vertical_left_renders() {
615        let sb = Scrollbar::new(ScrollbarOrientation::VerticalLeft);
616        let area = Rect::new(0, 0, 1, 10);
617        let mut pool = GraphemePool::new();
618        let mut frame = Frame::new(1, 10, &mut pool);
619        let mut state = ScrollbarState::new(100, 0, 10);
620        StatefulWidget::render(&sb, area, &mut frame, &mut state);
621
622        let top_cell = frame.buffer.get(0, 0).unwrap();
623        assert!(top_cell.content.as_char().is_some());
624    }
625
626    #[test]
627    fn scrollbar_horizontal_renders() {
628        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalBottom);
629        let area = Rect::new(0, 0, 10, 1);
630        let mut pool = GraphemePool::new();
631        let mut frame = Frame::new(10, 1, &mut pool);
632        let mut state = ScrollbarState::new(100, 0, 10);
633        StatefulWidget::render(&sb, area, &mut frame, &mut state);
634
635        let left_cell = frame.buffer.get(0, 0).unwrap();
636        assert!(left_cell.content.as_char().is_some());
637    }
638
639    #[test]
640    fn scrollbar_thumb_moves_with_position() {
641        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
642        let area = Rect::new(0, 0, 1, 10);
643
644        // Position at start
645        let mut pool1 = GraphemePool::new();
646        let mut frame1 = Frame::new(1, 10, &mut pool1);
647        let mut state1 = ScrollbarState::new(100, 0, 10);
648        StatefulWidget::render(&sb, area, &mut frame1, &mut state1);
649
650        // Position at end
651        let mut pool2 = GraphemePool::new();
652        let mut frame2 = Frame::new(1, 10, &mut pool2);
653        let mut state2 = ScrollbarState::new(100, 90, 10);
654        StatefulWidget::render(&sb, area, &mut frame2, &mut state2);
655
656        // The thumb char (█) should be at different positions
657        let thumb_char = '█';
658        let thumb_pos_1 = (0..10u16)
659            .find(|&y| frame1.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
660        let thumb_pos_2 = (0..10u16)
661            .find(|&y| frame2.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
662
663        // At start, thumb should be near top; at end, near bottom
664        assert!(thumb_pos_1.unwrap_or(0) < thumb_pos_2.unwrap_or(0));
665    }
666
667    #[test]
668    fn scrollbar_state_constructor() {
669        let state = ScrollbarState::new(200, 50, 20);
670        assert_eq!(state.content_length, 200);
671        assert_eq!(state.position, 50);
672        assert_eq!(state.viewport_length, 20);
673    }
674
675    #[test]
676    fn scrollbar_content_fits_viewport() {
677        // When viewport >= content, thumb should fill the whole track
678        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
679        let area = Rect::new(0, 0, 1, 10);
680        let mut pool = GraphemePool::new();
681        let mut frame = Frame::new(1, 10, &mut pool);
682        let mut state = ScrollbarState::new(5, 0, 10);
683        StatefulWidget::render(&sb, area, &mut frame, &mut state);
684
685        // All cells should be thumb (█)
686        let thumb_char = '█';
687        for y in 0..10u16 {
688            assert_eq!(
689                frame.buffer.get(0, y).unwrap().content.as_char(),
690                Some(thumb_char)
691            );
692        }
693    }
694
695    #[test]
696    fn scrollbar_horizontal_top_renders() {
697        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalTop);
698        let area = Rect::new(0, 0, 10, 1);
699        let mut pool = GraphemePool::new();
700        let mut frame = Frame::new(10, 1, &mut pool);
701        let mut state = ScrollbarState::new(100, 0, 10);
702        StatefulWidget::render(&sb, area, &mut frame, &mut state);
703
704        let left_cell = frame.buffer.get(0, 0).unwrap();
705        assert!(left_cell.content.as_char().is_some());
706    }
707
708    #[test]
709    fn scrollbar_custom_symbols() {
710        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight).symbols(
711            ".",
712            "#",
713            Some("^"),
714            Some("v"),
715        );
716        let area = Rect::new(0, 0, 1, 5);
717        let mut pool = GraphemePool::new();
718        let mut frame = Frame::new(1, 5, &mut pool);
719        let mut state = ScrollbarState::new(50, 0, 10);
720        StatefulWidget::render(&sb, area, &mut frame, &mut state);
721
722        // Should use our custom symbols
723        let mut chars: Vec<Option<char>> = Vec::new();
724        for y in 0..5u16 {
725            chars.push(frame.buffer.get(0, y).unwrap().content.as_char());
726        }
727        // At least some cells should have our custom chars
728        assert!(chars.contains(&Some('#')) || chars.contains(&Some('.')));
729    }
730
731    #[test]
732    fn scrollbar_position_clamped_beyond_max() {
733        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
734        let area = Rect::new(0, 0, 1, 10);
735        let mut pool = GraphemePool::new();
736        let mut frame = Frame::new(1, 10, &mut pool);
737        // Position way beyond content_length
738        let mut state = ScrollbarState::new(100, 500, 10);
739        StatefulWidget::render(&sb, area, &mut frame, &mut state);
740
741        // Should still render without panic, thumb at bottom
742        let thumb_char = '█';
743        let thumb_pos = (0..10u16)
744            .find(|&y| frame.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
745        assert!(thumb_pos.is_some());
746    }
747
748    #[test]
749    fn scrollbar_state_default() {
750        let state = ScrollbarState::default();
751        assert_eq!(state.content_length, 0);
752        assert_eq!(state.position, 0);
753        assert_eq!(state.viewport_length, 0);
754    }
755
756    #[test]
757    fn scrollbar_widget_trait_renders() {
758        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
759        let area = Rect::new(0, 0, 1, 5);
760        let mut pool = GraphemePool::new();
761        let mut frame = Frame::new(1, 5, &mut pool);
762        // Widget trait uses default state (content_length=0, so no rendering)
763        Widget::render(&sb, area, &mut frame);
764        // Should not panic with default state
765    }
766
767    #[test]
768    fn scrollbar_orientation_default_is_vertical_right() {
769        assert_eq!(
770            ScrollbarOrientation::default(),
771            ScrollbarOrientation::VerticalRight
772        );
773    }
774
775    // --- Degradation tests ---
776
777    #[test]
778    fn degradation_essential_only_skips_entirely() {
779        use ftui_render::budget::DegradationLevel;
780
781        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
782        let area = Rect::new(0, 0, 1, 10);
783        let mut pool = GraphemePool::new();
784        let mut frame = Frame::new(1, 10, &mut pool);
785        frame.buffer.degradation = DegradationLevel::EssentialOnly;
786        let mut state = ScrollbarState::new(100, 0, 10);
787        frame.buffer.degradation = DegradationLevel::Full;
788        StatefulWidget::render(&sb, area, &mut frame, &mut state);
789        frame.buffer.degradation = DegradationLevel::EssentialOnly;
790        StatefulWidget::render(&sb, area, &mut frame, &mut state);
791
792        for y in 0..10u16 {
793            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
794        }
795        assert!(state.track_layout.is_none());
796    }
797
798    #[test]
799    fn degradation_skeleton_skips_entirely() {
800        use ftui_render::budget::DegradationLevel;
801
802        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
803        let area = Rect::new(0, 0, 1, 10);
804        let mut pool = GraphemePool::new();
805        let mut frame = Frame::new(1, 10, &mut pool);
806        frame.buffer.degradation = DegradationLevel::Skeleton;
807        let mut state = ScrollbarState::new(100, 0, 10);
808        frame.buffer.degradation = DegradationLevel::Full;
809        StatefulWidget::render(&sb, area, &mut frame, &mut state);
810        frame.buffer.degradation = DegradationLevel::Skeleton;
811        StatefulWidget::render(&sb, area, &mut frame, &mut state);
812
813        for y in 0..10u16 {
814            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
815        }
816        assert!(state.track_layout.is_none());
817    }
818
819    #[test]
820    fn degradation_full_renders_scrollbar() {
821        use ftui_render::budget::DegradationLevel;
822
823        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
824        let area = Rect::new(0, 0, 1, 10);
825        let mut pool = GraphemePool::new();
826        let mut frame = Frame::new(1, 10, &mut pool);
827        frame.buffer.degradation = DegradationLevel::Full;
828        let mut state = ScrollbarState::new(100, 0, 10);
829        StatefulWidget::render(&sb, area, &mut frame, &mut state);
830
831        // Should render something (thumb or track)
832        let top_cell = frame.buffer.get(0, 0).unwrap();
833        assert!(top_cell.content.as_char().is_some());
834    }
835
836    #[test]
837    fn degradation_simple_borders_still_renders() {
838        use ftui_render::budget::DegradationLevel;
839
840        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
841        let area = Rect::new(0, 0, 1, 10);
842        let mut pool = GraphemePool::new();
843        let mut frame = Frame::new(1, 10, &mut pool);
844        frame.buffer.degradation = DegradationLevel::SimpleBorders;
845        let mut state = ScrollbarState::new(100, 0, 10);
846        StatefulWidget::render(&sb, area, &mut frame, &mut state);
847
848        // SimpleBorders still renders decorative content
849        let top_cell = frame.buffer.get(0, 0).unwrap();
850        assert!(top_cell.content.as_char().is_some());
851    }
852
853    #[test]
854    fn scrollbar_wide_symbols_horizontal() {
855        let sb =
856            Scrollbar::new(ScrollbarOrientation::HorizontalBottom).symbols("🔴", "👍", None, None);
857        // Area width 4. Expect "🔴🔴" (2 chars * 2 width = 4 cells)
858        let area = Rect::new(0, 0, 4, 1);
859        let mut pool = GraphemePool::new();
860        let mut frame = Frame::new(4, 1, &mut pool);
861        // Track only (thumb size 0 or pos 0?)
862        // Let's make thumb small/invisible or check track part.
863        // If content_length=10, viewport=10, thumb fills all.
864        // Let's fill with thumb "👍"
865        let mut state = ScrollbarState::new(10, 0, 10);
866
867        StatefulWidget::render(&sb, area, &mut frame, &mut state);
868
869        // x=0: Head "👍" (wide emoji stored as grapheme, not direct char)
870        let c0 = frame.buffer.get(0, 0).unwrap();
871        assert!(!c0.is_empty() && !c0.is_continuation()); // Head
872        // x=1: Continuation
873        let c1 = frame.buffer.get(1, 0).unwrap();
874        assert!(c1.is_continuation());
875
876        // x=2: Head "👍"
877        let c2 = frame.buffer.get(2, 0).unwrap();
878        assert!(!c2.is_empty() && !c2.is_continuation()); // Head
879        // x=3: Continuation
880        let c3 = frame.buffer.get(3, 0).unwrap();
881        assert!(c3.is_continuation());
882    }
883
884    #[test]
885    fn scrollbar_wide_symbols_vertical() {
886        let sb =
887            Scrollbar::new(ScrollbarOrientation::VerticalRight).symbols("🔴", "👍", None, None);
888        // Area height 2. Width 2 (to fit the wide char).
889        let area = Rect::new(0, 0, 2, 2);
890        let mut pool = GraphemePool::new();
891        let mut frame = Frame::new(2, 2, &mut pool);
892        let mut state = ScrollbarState::new(10, 0, 10); // Fill with thumb
893
894        StatefulWidget::render(&sb, area, &mut frame, &mut state);
895
896        // Row 0: "👍" at x=0 (wide emoji stored as grapheme, not direct char)
897        let r0_c0 = frame.buffer.get(0, 0).unwrap();
898        assert!(!r0_c0.is_empty() && !r0_c0.is_continuation()); // Head
899        let r0_c1 = frame.buffer.get(1, 0).unwrap();
900        assert!(r0_c1.is_continuation()); // Tail
901
902        // Row 1: "👍" at x=0 (should NOT be skipped)
903        let r1_c0 = frame.buffer.get(0, 1).unwrap();
904        assert!(!r1_c0.is_empty() && !r1_c0.is_continuation()); // Head
905        let r1_c1 = frame.buffer.get(1, 1).unwrap();
906        assert!(r1_c1.is_continuation()); // Tail
907    }
908
909    #[test]
910    fn scrollbar_wide_symbol_clips_drawing_and_hits_to_area() {
911        // Regression: wide symbols must not draw/register hit cells outside the widget area.
912        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
913            .symbols("🔴", "👍", None, None)
914            .hit_id(HitId::new(1));
915        let area = Rect::new(0, 0, 3, 1);
916        let mut pool = GraphemePool::new();
917        let mut frame = Frame::with_hit_grid(5, 1, &mut pool);
918        let mut state = ScrollbarState::new(3, 0, 3); // Thumb fills the track.
919
920        StatefulWidget::render(&sb, area, &mut frame, &mut state);
921
922        // x=3 is outside the widget area (area.right() == 3). It must remain untouched.
923        let outside = frame.buffer.get(3, 0).unwrap();
924        assert!(outside.is_empty(), "cell outside area should remain empty");
925        assert!(frame.hit_test(3, 0).is_none(), "no hit outside area");
926    }
927
928    #[test]
929    fn scrollbar_wide_symbol_vertical_clips_drawing_and_hits_to_area() {
930        let sb = Scrollbar::new(ScrollbarOrientation::VerticalLeft)
931            .symbols("🔴", "👍", None, None)
932            .hit_id(HitId::new(1));
933        let area = Rect::new(0, 0, 1, 2);
934        let mut pool = GraphemePool::new();
935        let mut frame = Frame::with_hit_grid(2, 2, &mut pool);
936        let mut state = ScrollbarState::new(10, 0, 10); // Thumb fills the track.
937
938        StatefulWidget::render(&sb, area, &mut frame, &mut state);
939
940        // x=1 is outside the widget area (area.right() == 1). It must remain untouched.
941        let outside = frame.buffer.get(1, 0).unwrap();
942        assert!(outside.is_empty(), "cell outside area should remain empty");
943        assert!(frame.hit_test(1, 0).is_none(), "no hit outside area");
944    }
945
946    #[test]
947    fn scrollbar_vertical_right_never_draws_left_of_area_for_wide_symbols() {
948        // Regression: when the area is narrower than the symbol, VerticalRight must not
949        // shift the draw position left of the widget area.
950        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight)
951            .symbols("🔴", "👍", None, None)
952            .hit_id(HitId::new(1));
953        let area = Rect::new(2, 0, 1, 2);
954        let mut pool = GraphemePool::new();
955        let mut frame = Frame::with_hit_grid(4, 2, &mut pool);
956        let mut state = ScrollbarState::new(10, 0, 10);
957
958        StatefulWidget::render(&sb, area, &mut frame, &mut state);
959
960        // x=1 is left of the widget area (area.left() == 2). It must remain untouched.
961        let outside = frame.buffer.get(1, 0).unwrap();
962        assert!(outside.is_empty(), "cell left of area should remain empty");
963        assert!(frame.hit_test(1, 0).is_none(), "no hit left of area");
964    }
965
966    // --- Mouse handling tests ---
967
968    use crate::mouse::MouseResult;
969    use ftui_core::event::{MouseButton, MouseEvent, MouseEventKind};
970
971    #[test]
972    fn scrollbar_state_begin_button() {
973        let mut state = ScrollbarState::new(100, 10, 20);
974        let data = SCROLLBAR_PART_BEGIN << 56;
975        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
976        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
977        let result = state.handle_mouse(&event, hit, HitId::new(1));
978        assert_eq!(result, MouseResult::Scrolled);
979        assert_eq!(state.position, 9);
980    }
981
982    #[test]
983    fn scrollbar_state_end_button() {
984        let mut state = ScrollbarState::new(100, 10, 20);
985        let data = SCROLLBAR_PART_END << 56;
986        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
987        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
988        let result = state.handle_mouse(&event, hit, HitId::new(1));
989        assert_eq!(result, MouseResult::Scrolled);
990        assert_eq!(state.position, 11);
991    }
992
993    #[test]
994    fn scrollbar_state_track_click() {
995        let mut state = ScrollbarState::new(100, 0, 20);
996        let track_len = 20u64;
997        let track_pos = 10u64;
998        let data = (SCROLLBAR_PART_TRACK << 56)
999            | ((track_len & 0x0FFF_FFFF) << 28)
1000            | (track_pos & 0x0FFF_FFFF);
1001        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1002        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1003        let result = state.handle_mouse(&event, hit, HitId::new(1));
1004        assert_eq!(result, MouseResult::Scrolled);
1005        // Track click maps proportionally to content position, centered on thumb.
1006        assert_eq!(state.position, 40);
1007    }
1008
1009    #[test]
1010    fn scrollbar_state_track_click_clamps() {
1011        let mut state = ScrollbarState::new(100, 0, 20);
1012        let track_len = 20u64;
1013        let track_pos = 95u64;
1014        let data = (SCROLLBAR_PART_TRACK << 56)
1015            | ((track_len & 0x0FFF_FFFF) << 28)
1016            | (track_pos & 0x0FFF_FFFF);
1017        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1018        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1019        let result = state.handle_mouse(&event, hit, HitId::new(1));
1020        assert_eq!(result, MouseResult::Scrolled);
1021        assert_eq!(state.position, 80); // content_length - viewport_length
1022    }
1023
1024    #[test]
1025    fn scrollbar_state_thumb_drag_updates_position() {
1026        let mut state = ScrollbarState::new(100, 0, 20);
1027        let track_len = 20u64;
1028        let track_pos = 19u64;
1029        let data = (SCROLLBAR_PART_THUMB << 56)
1030            | ((track_len & 0x0FFF_FFFF) << 28)
1031            | (track_pos & 0x0FFF_FFFF);
1032        let event = MouseEvent::new(MouseEventKind::Drag(MouseButton::Left), 0, 0);
1033        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1034        let result = state.handle_mouse(&event, hit, HitId::new(1));
1035        assert_eq!(result, MouseResult::Scrolled);
1036        assert_eq!(state.position, 80);
1037    }
1038
1039    #[test]
1040    fn scrollbar_state_scroll_wheel_up() {
1041        let mut state = ScrollbarState::new(100, 10, 20);
1042        let event = MouseEvent::new(MouseEventKind::ScrollUp, 0, 0);
1043        let result = state.handle_mouse(&event, None, HitId::new(1));
1044        assert_eq!(result, MouseResult::Scrolled);
1045        assert_eq!(state.position, 7);
1046    }
1047
1048    #[test]
1049    fn scrollbar_state_scroll_wheel_down() {
1050        let mut state = ScrollbarState::new(100, 10, 20);
1051        let event = MouseEvent::new(MouseEventKind::ScrollDown, 0, 0);
1052        let result = state.handle_mouse(&event, None, HitId::new(1));
1053        assert_eq!(result, MouseResult::Scrolled);
1054        assert_eq!(state.position, 13);
1055    }
1056
1057    #[test]
1058    fn scrollbar_state_scroll_down_clamps() {
1059        let mut state = ScrollbarState::new(100, 78, 20);
1060        state.scroll_down(5);
1061        assert_eq!(state.position, 80); // max = 100 - 20
1062    }
1063
1064    #[test]
1065    fn scrollbar_state_scroll_up_clamps() {
1066        let mut state = ScrollbarState::new(100, 2, 20);
1067        state.scroll_up(5);
1068        assert_eq!(state.position, 0);
1069    }
1070
1071    #[test]
1072    fn scrollbar_state_wrong_id_ignored() {
1073        let mut state = ScrollbarState::new(100, 10, 20);
1074        let data = SCROLLBAR_PART_BEGIN << 56;
1075        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1076        let hit = Some((HitId::new(99), HitRegion::Scrollbar, data));
1077        let result = state.handle_mouse(&event, hit, HitId::new(1));
1078        assert_eq!(result, MouseResult::Ignored);
1079        assert_eq!(state.position, 10);
1080    }
1081
1082    #[test]
1083    fn scrollbar_state_right_click_ignored() {
1084        let mut state = ScrollbarState::new(100, 10, 20);
1085        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Right), 0, 0);
1086        let result = state.handle_mouse(&event, None, HitId::new(1));
1087        assert_eq!(result, MouseResult::Ignored);
1088    }
1089}