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        // Not for an empty area: nothing is drawn for one, so a node would
355        // describe a widget that was never on screen, and every such node
356        // collides on the id of the same empty rect
357        // (bd-a11y-sibling-id-collision-6zqd2). The emptiness check below is
358        // compound and does cleanup, so the guard sits on the push rather than
359        // the push moving past it.
360        if frame.a11y_enabled() && !area.is_empty() {
361            frame.push_a11y_nodes(ftui_a11y::Accessible::accessibility_nodes(self, area));
362        }
363        #[cfg(feature = "tracing")]
364        let _span = tracing::debug_span!(
365            "widget_render",
366            widget = "Scrollbar",
367            x = area.x,
368            y = area.y,
369            w = area.width,
370            h = area.height
371        )
372        .entered();
373
374        // Scrollbar is decorative — skip at EssentialOnly+
375        if !frame.should_render_widget(false) {
376            state.track_layout = None;
377            clear_text_area(frame, area, Style::default());
378            return;
379        }
380
381        if area.is_empty() || state.content_length == 0 {
382            state.track_layout = None;
383            clear_text_area(frame, area, Style::default());
384            return;
385        }
386
387        let is_vertical = match self.orientation {
388            ScrollbarOrientation::VerticalRight | ScrollbarOrientation::VerticalLeft => true,
389            ScrollbarOrientation::HorizontalBottom | ScrollbarOrientation::HorizontalTop => false,
390        };
391
392        let length = if is_vertical { area.height } else { area.width } as usize;
393        if length == 0 {
394            state.track_layout = None;
395            return;
396        }
397
398        // Calculate layout
399        let start_offset = if let Some(s) = self.begin_symbol {
400            if is_vertical { 1 } else { display_width(s) }
401        } else {
402            0
403        };
404        let end_offset = if let Some(s) = self.end_symbol {
405            if is_vertical { 1 } else { display_width(s) }
406        } else {
407            0
408        };
409
410        // Effective track excludes buttons
411        let track_len = length.saturating_sub(start_offset + end_offset);
412
413        // Calculate thumb size and position within the effective track
414        let (thumb_offset, thumb_size) = state.calc_thumb_geometry(track_len);
415
416        // Symbols
417        let track_char = self
418            .track_symbol
419            .unwrap_or(if is_vertical { "│" } else { "─" });
420        let thumb_char = self.thumb_symbol.unwrap_or("█");
421        let begin_char = self
422            .begin_symbol
423            .unwrap_or(if is_vertical { "▲" } else { "◄" });
424        let end_char = self
425            .end_symbol
426            .unwrap_or(if is_vertical { "▼" } else { "►" });
427
428        // Update track layout for mouse interaction fallback
429        let max_w = display_width(track_char)
430            .max(display_width(thumb_char))
431            .max(1);
432        let track_rect = if is_vertical {
433            let x = match self.orientation {
434                ScrollbarOrientation::VerticalRight => {
435                    area.right().saturating_sub(max_w as u16).max(area.left())
436                }
437                ScrollbarOrientation::VerticalLeft => area.left(),
438                _ => unreachable!(),
439            };
440            Rect::new(
441                x,
442                area.top().saturating_add(start_offset as u16),
443                max_w as u16,
444                track_len as u16,
445            )
446        } else {
447            let y = match self.orientation {
448                ScrollbarOrientation::HorizontalBottom => area.bottom().saturating_sub(1),
449                ScrollbarOrientation::HorizontalTop => area.top(),
450                _ => unreachable!(),
451            };
452            Rect::new(
453                area.left().saturating_add(start_offset as u16),
454                y,
455                track_len as u16,
456                1,
457            )
458        };
459        state.track_layout = Some(TrackLayout {
460            rect: track_rect,
461            is_vertical,
462        });
463
464        // Draw
465        let mut next_draw_index = 0;
466        for i in 0..length {
467            if i < next_draw_index {
468                continue;
469            }
470
471            // Determine part type and relative position
472            let (symbol, part, rel_pos) = if i < start_offset {
473                (begin_char, SCROLLBAR_PART_BEGIN, 0)
474            } else if i >= length.saturating_sub(end_offset) {
475                (end_char, SCROLLBAR_PART_END, 0)
476            } else {
477                let track_idx = i - start_offset;
478                let is_thumb = track_idx >= thumb_offset && track_idx < thumb_offset + thumb_size;
479                if is_thumb {
480                    (thumb_char, SCROLLBAR_PART_THUMB, track_idx)
481                } else {
482                    (track_char, SCROLLBAR_PART_TRACK, track_idx)
483                }
484            };
485
486            let symbol_width = display_width(symbol);
487            if is_vertical {
488                next_draw_index = i + 1;
489            } else {
490                next_draw_index = i + symbol_width;
491            }
492
493            let style = if !frame.buffer.degradation.apply_styling() {
494                Style::default()
495            } else if part == SCROLLBAR_PART_THUMB {
496                self.thumb_style
497            } else {
498                self.track_style
499            };
500
501            let (x, y) = if is_vertical {
502                let x = match self.orientation {
503                    ScrollbarOrientation::VerticalRight => area
504                        .right()
505                        .saturating_sub(symbol_width.max(1) as u16)
506                        .max(area.left()),
507                    ScrollbarOrientation::VerticalLeft => area.left(),
508                    _ => unreachable!(),
509                };
510                (x, area.top().saturating_add(i as u16))
511            } else {
512                let y = match self.orientation {
513                    ScrollbarOrientation::HorizontalBottom => area.bottom().saturating_sub(1),
514                    ScrollbarOrientation::HorizontalTop => area.top(),
515                    _ => unreachable!(),
516                };
517                (area.left().saturating_add(i as u16), y)
518            };
519
520            // Only draw if within bounds
521            if x < area.right() && y < area.bottom() {
522                draw_text_span(frame, x, y, symbol, style, area.right());
523
524                if let Some(id) = self.hit_id {
525                    // Encode data: [8: part] [28: track_len] [28: track_pos]
526                    let data = (part << 56)
527                        | ((track_len as u64 & 0x0FFF_FFFF) << 28)
528                        | (rel_pos as u64 & 0x0FFF_FFFF);
529
530                    let hit_w = (symbol_width.max(1) as u16).min(area.right().saturating_sub(x));
531                    frame.register_hit(Rect::new(x, y, hit_w, 1), id, HitRegion::Scrollbar, data);
532                }
533            }
534        }
535    }
536}
537
538impl<'a> Widget for Scrollbar<'a> {
539    fn render(&self, area: Rect, frame: &mut Frame) {
540        let mut state = ScrollbarState::default();
541        StatefulWidget::render(self, area, frame, &mut state);
542    }
543}
544
545// ============================================================================
546// Accessibility
547// ============================================================================
548
549impl ftui_a11y::Accessible for Scrollbar<'_> {
550    fn accessibility_nodes(&self, area: Rect) -> Vec<ftui_a11y::node::A11yNodeInfo> {
551        use ftui_a11y::node::{A11yNodeInfo, A11yRole, A11yState};
552
553        let id = crate::a11y_node_id(area);
554        let orientation = match self.orientation {
555            ScrollbarOrientation::VerticalRight | ScrollbarOrientation::VerticalLeft => "vertical",
556            ScrollbarOrientation::HorizontalBottom | ScrollbarOrientation::HorizontalTop => {
557                "horizontal"
558            }
559        };
560        let name = format!("{orientation} scrollbar");
561        let node = A11yNodeInfo::new(id, A11yRole::ScrollBar, area)
562            .with_name(name)
563            .with_state(A11yState {
564                // Scrollbars are always interactive but don't themselves hold focus;
565                // the viewport they scroll is the focusable element.
566                ..A11yState::default()
567            });
568        vec![node]
569    }
570}
571
572#[cfg(test)]
573mod tests {
574    use super::*;
575    use ftui_render::grapheme_pool::GraphemePool;
576
577    #[test]
578    fn scrollbar_empty_area() {
579        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
580        let area = Rect::new(0, 0, 0, 0);
581        let mut pool = GraphemePool::new();
582        let mut frame = Frame::new(1, 1, &mut pool);
583        let mut state = ScrollbarState::new(100, 0, 10);
584        StatefulWidget::render(&sb, area, &mut frame, &mut state);
585    }
586
587    #[test]
588    fn scrollbar_zero_content() {
589        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
590        let area = Rect::new(0, 0, 1, 10);
591        let mut pool = GraphemePool::new();
592        let mut frame = Frame::new(1, 10, &mut pool);
593        let mut state = ScrollbarState::new(100, 0, 10);
594        StatefulWidget::render(&sb, area, &mut frame, &mut state);
595
596        state.content_length = 0;
597        StatefulWidget::render(&sb, area, &mut frame, &mut state);
598
599        for y in 0..10u16 {
600            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
601        }
602        assert!(state.track_layout.is_none());
603    }
604
605    #[test]
606    fn scrollbar_vertical_right_renders() {
607        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
608        let area = Rect::new(0, 0, 1, 10);
609        let mut pool = GraphemePool::new();
610        let mut frame = Frame::new(1, 10, &mut pool);
611        let mut state = ScrollbarState::new(100, 0, 10);
612        StatefulWidget::render(&sb, area, &mut frame, &mut state);
613
614        // Thumb should be at the top (position=0), track should have chars
615        let top_cell = frame.buffer.get(0, 0).unwrap();
616        assert!(top_cell.content.as_char().is_some());
617    }
618
619    #[test]
620    fn scrollbar_vertical_left_renders() {
621        let sb = Scrollbar::new(ScrollbarOrientation::VerticalLeft);
622        let area = Rect::new(0, 0, 1, 10);
623        let mut pool = GraphemePool::new();
624        let mut frame = Frame::new(1, 10, &mut pool);
625        let mut state = ScrollbarState::new(100, 0, 10);
626        StatefulWidget::render(&sb, area, &mut frame, &mut state);
627
628        let top_cell = frame.buffer.get(0, 0).unwrap();
629        assert!(top_cell.content.as_char().is_some());
630    }
631
632    #[test]
633    fn scrollbar_horizontal_renders() {
634        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalBottom);
635        let area = Rect::new(0, 0, 10, 1);
636        let mut pool = GraphemePool::new();
637        let mut frame = Frame::new(10, 1, &mut pool);
638        let mut state = ScrollbarState::new(100, 0, 10);
639        StatefulWidget::render(&sb, area, &mut frame, &mut state);
640
641        let left_cell = frame.buffer.get(0, 0).unwrap();
642        assert!(left_cell.content.as_char().is_some());
643    }
644
645    #[test]
646    fn scrollbar_thumb_moves_with_position() {
647        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
648        let area = Rect::new(0, 0, 1, 10);
649
650        // Position at start
651        let mut pool1 = GraphemePool::new();
652        let mut frame1 = Frame::new(1, 10, &mut pool1);
653        let mut state1 = ScrollbarState::new(100, 0, 10);
654        StatefulWidget::render(&sb, area, &mut frame1, &mut state1);
655
656        // Position at end
657        let mut pool2 = GraphemePool::new();
658        let mut frame2 = Frame::new(1, 10, &mut pool2);
659        let mut state2 = ScrollbarState::new(100, 90, 10);
660        StatefulWidget::render(&sb, area, &mut frame2, &mut state2);
661
662        // The thumb char (█) should be at different positions
663        let thumb_char = '█';
664        let thumb_pos_1 = (0..10u16)
665            .find(|&y| frame1.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
666        let thumb_pos_2 = (0..10u16)
667            .find(|&y| frame2.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
668
669        // At start, thumb should be near top; at end, near bottom
670        assert!(thumb_pos_1.unwrap_or(0) < thumb_pos_2.unwrap_or(0));
671    }
672
673    #[test]
674    fn scrollbar_state_constructor() {
675        let state = ScrollbarState::new(200, 50, 20);
676        assert_eq!(state.content_length, 200);
677        assert_eq!(state.position, 50);
678        assert_eq!(state.viewport_length, 20);
679    }
680
681    #[test]
682    fn scrollbar_content_fits_viewport() {
683        // When viewport >= content, thumb should fill the whole track
684        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
685        let area = Rect::new(0, 0, 1, 10);
686        let mut pool = GraphemePool::new();
687        let mut frame = Frame::new(1, 10, &mut pool);
688        let mut state = ScrollbarState::new(5, 0, 10);
689        StatefulWidget::render(&sb, area, &mut frame, &mut state);
690
691        // All cells should be thumb (█)
692        let thumb_char = '█';
693        for y in 0..10u16 {
694            assert_eq!(
695                frame.buffer.get(0, y).unwrap().content.as_char(),
696                Some(thumb_char)
697            );
698        }
699    }
700
701    #[test]
702    fn scrollbar_horizontal_top_renders() {
703        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalTop);
704        let area = Rect::new(0, 0, 10, 1);
705        let mut pool = GraphemePool::new();
706        let mut frame = Frame::new(10, 1, &mut pool);
707        let mut state = ScrollbarState::new(100, 0, 10);
708        StatefulWidget::render(&sb, area, &mut frame, &mut state);
709
710        let left_cell = frame.buffer.get(0, 0).unwrap();
711        assert!(left_cell.content.as_char().is_some());
712    }
713
714    #[test]
715    fn scrollbar_custom_symbols() {
716        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight).symbols(
717            ".",
718            "#",
719            Some("^"),
720            Some("v"),
721        );
722        let area = Rect::new(0, 0, 1, 5);
723        let mut pool = GraphemePool::new();
724        let mut frame = Frame::new(1, 5, &mut pool);
725        let mut state = ScrollbarState::new(50, 0, 10);
726        StatefulWidget::render(&sb, area, &mut frame, &mut state);
727
728        // Should use our custom symbols
729        let mut chars: Vec<Option<char>> = Vec::new();
730        for y in 0..5u16 {
731            chars.push(frame.buffer.get(0, y).unwrap().content.as_char());
732        }
733        // At least some cells should have our custom chars
734        assert!(chars.contains(&Some('#')) || chars.contains(&Some('.')));
735    }
736
737    #[test]
738    fn scrollbar_position_clamped_beyond_max() {
739        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
740        let area = Rect::new(0, 0, 1, 10);
741        let mut pool = GraphemePool::new();
742        let mut frame = Frame::new(1, 10, &mut pool);
743        // Position way beyond content_length
744        let mut state = ScrollbarState::new(100, 500, 10);
745        StatefulWidget::render(&sb, area, &mut frame, &mut state);
746
747        // Should still render without panic, thumb at bottom
748        let thumb_char = '█';
749        let thumb_pos = (0..10u16)
750            .find(|&y| frame.buffer.get(0, y).unwrap().content.as_char() == Some(thumb_char));
751        assert!(thumb_pos.is_some());
752    }
753
754    #[test]
755    fn scrollbar_state_default() {
756        let state = ScrollbarState::default();
757        assert_eq!(state.content_length, 0);
758        assert_eq!(state.position, 0);
759        assert_eq!(state.viewport_length, 0);
760    }
761
762    #[test]
763    fn scrollbar_widget_trait_renders() {
764        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
765        let area = Rect::new(0, 0, 1, 5);
766        let mut pool = GraphemePool::new();
767        let mut frame = Frame::new(1, 5, &mut pool);
768        // Widget trait uses default state (content_length=0, so no rendering)
769        Widget::render(&sb, area, &mut frame);
770        // Should not panic with default state
771    }
772
773    #[test]
774    fn scrollbar_orientation_default_is_vertical_right() {
775        assert_eq!(
776            ScrollbarOrientation::default(),
777            ScrollbarOrientation::VerticalRight
778        );
779    }
780
781    // --- Degradation tests ---
782
783    #[test]
784    fn degradation_essential_only_skips_entirely() {
785        use ftui_render::budget::DegradationLevel;
786
787        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
788        let area = Rect::new(0, 0, 1, 10);
789        let mut pool = GraphemePool::new();
790        let mut frame = Frame::new(1, 10, &mut pool);
791        frame.buffer.degradation = DegradationLevel::EssentialOnly;
792        let mut state = ScrollbarState::new(100, 0, 10);
793        frame.buffer.degradation = DegradationLevel::Full;
794        StatefulWidget::render(&sb, area, &mut frame, &mut state);
795        frame.buffer.degradation = DegradationLevel::EssentialOnly;
796        StatefulWidget::render(&sb, area, &mut frame, &mut state);
797
798        for y in 0..10u16 {
799            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
800        }
801        assert!(state.track_layout.is_none());
802    }
803
804    #[test]
805    fn scrollbar_skips_render_under_essential_only() {
806        degradation_essential_only_skips_entirely();
807    }
808
809    #[test]
810    fn degradation_skeleton_skips_entirely() {
811        use ftui_render::budget::DegradationLevel;
812
813        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
814        let area = Rect::new(0, 0, 1, 10);
815        let mut pool = GraphemePool::new();
816        let mut frame = Frame::new(1, 10, &mut pool);
817        frame.buffer.degradation = DegradationLevel::Skeleton;
818        let mut state = ScrollbarState::new(100, 0, 10);
819        frame.buffer.degradation = DegradationLevel::Full;
820        StatefulWidget::render(&sb, area, &mut frame, &mut state);
821        frame.buffer.degradation = DegradationLevel::Skeleton;
822        StatefulWidget::render(&sb, area, &mut frame, &mut state);
823
824        for y in 0..10u16 {
825            assert_eq!(frame.buffer.get(0, y).unwrap().content.as_char(), Some(' '));
826        }
827        assert!(state.track_layout.is_none());
828    }
829
830    #[test]
831    fn degradation_full_renders_scrollbar() {
832        use ftui_render::budget::DegradationLevel;
833
834        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
835        let area = Rect::new(0, 0, 1, 10);
836        let mut pool = GraphemePool::new();
837        let mut frame = Frame::new(1, 10, &mut pool);
838        frame.buffer.degradation = DegradationLevel::Full;
839        let mut state = ScrollbarState::new(100, 0, 10);
840        StatefulWidget::render(&sb, area, &mut frame, &mut state);
841
842        // Should render something (thumb or track)
843        let top_cell = frame.buffer.get(0, 0).unwrap();
844        assert!(top_cell.content.as_char().is_some());
845    }
846
847    #[test]
848    fn degradation_simple_borders_still_renders() {
849        use ftui_render::budget::DegradationLevel;
850
851        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight);
852        let area = Rect::new(0, 0, 1, 10);
853        let mut pool = GraphemePool::new();
854        let mut frame = Frame::new(1, 10, &mut pool);
855        frame.buffer.degradation = DegradationLevel::SimpleBorders;
856        let mut state = ScrollbarState::new(100, 0, 10);
857        StatefulWidget::render(&sb, area, &mut frame, &mut state);
858
859        // SimpleBorders still renders decorative content
860        let top_cell = frame.buffer.get(0, 0).unwrap();
861        assert!(top_cell.content.as_char().is_some());
862    }
863
864    #[test]
865    fn scrollbar_wide_symbols_horizontal() {
866        let sb =
867            Scrollbar::new(ScrollbarOrientation::HorizontalBottom).symbols("🔴", "👍", None, None);
868        // Area width 4. Expect "🔴🔴" (2 chars * 2 width = 4 cells)
869        let area = Rect::new(0, 0, 4, 1);
870        let mut pool = GraphemePool::new();
871        let mut frame = Frame::new(4, 1, &mut pool);
872        // Track only (thumb size 0 or pos 0?)
873        // Let's make thumb small/invisible or check track part.
874        // If content_length=10, viewport=10, thumb fills all.
875        // Let's fill with thumb "👍"
876        let mut state = ScrollbarState::new(10, 0, 10);
877
878        StatefulWidget::render(&sb, area, &mut frame, &mut state);
879
880        // x=0: Head "👍" (wide emoji stored as grapheme, not direct char)
881        let c0 = frame.buffer.get(0, 0).unwrap();
882        assert!(!c0.is_empty() && !c0.is_continuation()); // Head
883        // x=1: Continuation
884        let c1 = frame.buffer.get(1, 0).unwrap();
885        assert!(c1.is_continuation());
886
887        // x=2: Head "👍"
888        let c2 = frame.buffer.get(2, 0).unwrap();
889        assert!(!c2.is_empty() && !c2.is_continuation()); // Head
890        // x=3: Continuation
891        let c3 = frame.buffer.get(3, 0).unwrap();
892        assert!(c3.is_continuation());
893    }
894
895    #[test]
896    fn scrollbar_wide_symbols_vertical() {
897        let sb =
898            Scrollbar::new(ScrollbarOrientation::VerticalRight).symbols("🔴", "👍", None, None);
899        // Area height 2. Width 2 (to fit the wide char).
900        let area = Rect::new(0, 0, 2, 2);
901        let mut pool = GraphemePool::new();
902        let mut frame = Frame::new(2, 2, &mut pool);
903        let mut state = ScrollbarState::new(10, 0, 10); // Fill with thumb
904
905        StatefulWidget::render(&sb, area, &mut frame, &mut state);
906
907        // Row 0: "👍" at x=0 (wide emoji stored as grapheme, not direct char)
908        let r0_c0 = frame.buffer.get(0, 0).unwrap();
909        assert!(!r0_c0.is_empty() && !r0_c0.is_continuation()); // Head
910        let r0_c1 = frame.buffer.get(1, 0).unwrap();
911        assert!(r0_c1.is_continuation()); // Tail
912
913        // Row 1: "👍" at x=0 (should NOT be skipped)
914        let r1_c0 = frame.buffer.get(0, 1).unwrap();
915        assert!(!r1_c0.is_empty() && !r1_c0.is_continuation()); // Head
916        let r1_c1 = frame.buffer.get(1, 1).unwrap();
917        assert!(r1_c1.is_continuation()); // Tail
918    }
919
920    #[test]
921    fn scrollbar_wide_symbol_clips_drawing_and_hits_to_area() {
922        // Regression: wide symbols must not draw/register hit cells outside the widget area.
923        let sb = Scrollbar::new(ScrollbarOrientation::HorizontalBottom)
924            .symbols("🔴", "👍", None, None)
925            .hit_id(HitId::new(1));
926        let area = Rect::new(0, 0, 3, 1);
927        let mut pool = GraphemePool::new();
928        let mut frame = Frame::with_hit_grid(5, 1, &mut pool);
929        let mut state = ScrollbarState::new(3, 0, 3); // Thumb fills the track.
930
931        StatefulWidget::render(&sb, area, &mut frame, &mut state);
932
933        // x=3 is outside the widget area (area.right() == 3). It must remain untouched.
934        let outside = frame.buffer.get(3, 0).unwrap();
935        assert!(outside.is_empty(), "cell outside area should remain empty");
936        assert!(frame.hit_test(3, 0).is_none(), "no hit outside area");
937    }
938
939    #[test]
940    fn scrollbar_wide_symbol_vertical_clips_drawing_and_hits_to_area() {
941        let sb = Scrollbar::new(ScrollbarOrientation::VerticalLeft)
942            .symbols("🔴", "👍", None, None)
943            .hit_id(HitId::new(1));
944        let area = Rect::new(0, 0, 1, 2);
945        let mut pool = GraphemePool::new();
946        let mut frame = Frame::with_hit_grid(2, 2, &mut pool);
947        let mut state = ScrollbarState::new(10, 0, 10); // Thumb fills the track.
948
949        StatefulWidget::render(&sb, area, &mut frame, &mut state);
950
951        // x=1 is outside the widget area (area.right() == 1). It must remain untouched.
952        let outside = frame.buffer.get(1, 0).unwrap();
953        assert!(outside.is_empty(), "cell outside area should remain empty");
954        assert!(frame.hit_test(1, 0).is_none(), "no hit outside area");
955    }
956
957    #[test]
958    fn scrollbar_vertical_right_never_draws_left_of_area_for_wide_symbols() {
959        // Regression: when the area is narrower than the symbol, VerticalRight must not
960        // shift the draw position left of the widget area.
961        let sb = Scrollbar::new(ScrollbarOrientation::VerticalRight)
962            .symbols("🔴", "👍", None, None)
963            .hit_id(HitId::new(1));
964        let area = Rect::new(2, 0, 1, 2);
965        let mut pool = GraphemePool::new();
966        let mut frame = Frame::with_hit_grid(4, 2, &mut pool);
967        let mut state = ScrollbarState::new(10, 0, 10);
968
969        StatefulWidget::render(&sb, area, &mut frame, &mut state);
970
971        // x=1 is left of the widget area (area.left() == 2). It must remain untouched.
972        let outside = frame.buffer.get(1, 0).unwrap();
973        assert!(outside.is_empty(), "cell left of area should remain empty");
974        assert!(frame.hit_test(1, 0).is_none(), "no hit left of area");
975    }
976
977    // --- Mouse handling tests ---
978
979    use crate::mouse::MouseResult;
980    use ftui_core::event::{MouseButton, MouseEvent, MouseEventKind};
981
982    #[test]
983    fn scrollbar_state_begin_button() {
984        let mut state = ScrollbarState::new(100, 10, 20);
985        let data = SCROLLBAR_PART_BEGIN << 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, 9);
991    }
992
993    #[test]
994    fn scrollbar_state_end_button() {
995        let mut state = ScrollbarState::new(100, 10, 20);
996        let data = SCROLLBAR_PART_END << 56;
997        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
998        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
999        let result = state.handle_mouse(&event, hit, HitId::new(1));
1000        assert_eq!(result, MouseResult::Scrolled);
1001        assert_eq!(state.position, 11);
1002    }
1003
1004    #[test]
1005    fn scrollbar_state_track_click() {
1006        let mut state = ScrollbarState::new(100, 0, 20);
1007        let track_len = 20u64;
1008        let track_pos = 10u64;
1009        let data = (SCROLLBAR_PART_TRACK << 56)
1010            | ((track_len & 0x0FFF_FFFF) << 28)
1011            | (track_pos & 0x0FFF_FFFF);
1012        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1013        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1014        let result = state.handle_mouse(&event, hit, HitId::new(1));
1015        assert_eq!(result, MouseResult::Scrolled);
1016        // Track click maps proportionally to content position, centered on thumb.
1017        assert_eq!(state.position, 40);
1018    }
1019
1020    #[test]
1021    fn scrollbar_state_track_click_clamps() {
1022        let mut state = ScrollbarState::new(100, 0, 20);
1023        let track_len = 20u64;
1024        let track_pos = 95u64;
1025        let data = (SCROLLBAR_PART_TRACK << 56)
1026            | ((track_len & 0x0FFF_FFFF) << 28)
1027            | (track_pos & 0x0FFF_FFFF);
1028        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1029        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1030        let result = state.handle_mouse(&event, hit, HitId::new(1));
1031        assert_eq!(result, MouseResult::Scrolled);
1032        assert_eq!(state.position, 80); // content_length - viewport_length
1033    }
1034
1035    #[test]
1036    fn scrollbar_state_thumb_drag_updates_position() {
1037        let mut state = ScrollbarState::new(100, 0, 20);
1038        let track_len = 20u64;
1039        let track_pos = 19u64;
1040        let data = (SCROLLBAR_PART_THUMB << 56)
1041            | ((track_len & 0x0FFF_FFFF) << 28)
1042            | (track_pos & 0x0FFF_FFFF);
1043        let event = MouseEvent::new(MouseEventKind::Drag(MouseButton::Left), 0, 0);
1044        let hit = Some((HitId::new(1), HitRegion::Scrollbar, data));
1045        let result = state.handle_mouse(&event, hit, HitId::new(1));
1046        assert_eq!(result, MouseResult::Scrolled);
1047        assert_eq!(state.position, 80);
1048    }
1049
1050    #[test]
1051    fn scrollbar_state_scroll_wheel_up() {
1052        let mut state = ScrollbarState::new(100, 10, 20);
1053        let event = MouseEvent::new(MouseEventKind::ScrollUp, 0, 0);
1054        let result = state.handle_mouse(&event, None, HitId::new(1));
1055        assert_eq!(result, MouseResult::Scrolled);
1056        assert_eq!(state.position, 7);
1057    }
1058
1059    #[test]
1060    fn scrollbar_state_scroll_wheel_down() {
1061        let mut state = ScrollbarState::new(100, 10, 20);
1062        let event = MouseEvent::new(MouseEventKind::ScrollDown, 0, 0);
1063        let result = state.handle_mouse(&event, None, HitId::new(1));
1064        assert_eq!(result, MouseResult::Scrolled);
1065        assert_eq!(state.position, 13);
1066    }
1067
1068    #[test]
1069    fn scrollbar_state_scroll_down_clamps() {
1070        let mut state = ScrollbarState::new(100, 78, 20);
1071        state.scroll_down(5);
1072        assert_eq!(state.position, 80); // max = 100 - 20
1073    }
1074
1075    #[test]
1076    fn scrollbar_state_scroll_up_clamps() {
1077        let mut state = ScrollbarState::new(100, 2, 20);
1078        state.scroll_up(5);
1079        assert_eq!(state.position, 0);
1080    }
1081
1082    #[test]
1083    fn scrollbar_state_wrong_id_ignored() {
1084        let mut state = ScrollbarState::new(100, 10, 20);
1085        let data = SCROLLBAR_PART_BEGIN << 56;
1086        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1087        let hit = Some((HitId::new(99), HitRegion::Scrollbar, data));
1088        let result = state.handle_mouse(&event, hit, HitId::new(1));
1089        assert_eq!(result, MouseResult::Ignored);
1090        assert_eq!(state.position, 10);
1091    }
1092
1093    #[test]
1094    fn scrollbar_state_right_click_ignored() {
1095        let mut state = ScrollbarState::new(100, 10, 20);
1096        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Right), 0, 0);
1097        let result = state.handle_mouse(&event, None, HitId::new(1));
1098        assert_eq!(result, MouseResult::Ignored);
1099    }
1100}