Merge pull request #37 from preiter93/scroll-large-items

preiter93 · web-flow · commit 75f9149277a9 · 2026-03-28T18:39:00.000+01:00
feat: Add within-item scroll for large items
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,10 @@
 Released
 --------
 
+0.15.2 - 28 Mar 2026
+===================
+- feat: Scroll within large items before selecting the next (co-authored by @orlandohohmeier)
+
 0.15.1 - 28 Mar 2026
 ===================
 - feat: Add ScrollDirection with forward/backward direction
diff --git a/examples/var_sizes.rs b/examples/var_sizes.rs
@@ -4,20 +4,28 @@ use common::{Colors, Result, Terminal};
 use ratatui::crossterm::event::{self, Event, KeyCode, KeyEventKind};
 use ratatui::{
     prelude::*,
-    widgets::{Block, Borders, Widget},
+    widgets::{Block, Borders, Scrollbar, Widget},
 };
 use tui_widget_list::{ListBuilder, ListState, ListView};
 
-const SIZES: [u16; 19] = [32, 3, 4, 64, 6, 5, 4, 3, 3, 6, 5, 7, 3, 6, 9, 10, 4, 4, 6];
+const ITEMS: &[(&str, u16)] = &[
+    ("Header", 3),
+    ("Summary", 5),
+    ("Details", 30),
+    ("Note A", 4),
+    ("Note B", 4),
+    ("Body", 25),
+    ("Sidebar", 6),
+    ("Note C", 3),
+    ("Note D", 3),
+    ("Footer", 5),
+];
 
 fn main() -> Result<()> {
     let mut terminal = Terminal::init()?;
-
     App::default().run(&mut terminal)?;
-
     Terminal::reset()?;
     terminal.show_cursor()?;
-
     Ok(())
 }
 
@@ -29,7 +37,6 @@ impl App {
         let mut state = ListState::default();
         loop {
             terminal.draw_app(self, &mut state)?;
-
             if let Event::Key(key) = event::read()? {
                 if key.kind == KeyEventKind::Press {
                     match key.code {
@@ -46,51 +53,61 @@ impl App {
 
 impl StatefulWidget for &App {
     type State = ListState;
-    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State)
-    where
-        Self: Sized,
-    {
-        let item_count = SIZES.len();
-
-        let block = Block::default().borders(Borders::ALL).title("Outer block");
+    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
         let builder = ListBuilder::new(move |context| {
-            let size = SIZES[context.index];
-            let mut widget = LineItem::new(format!("Size: {size}"));
+            let (title, size) = ITEMS[context.index];
+            let label = format!(" {} (h={})", title, size);
+
+            let style = if context.is_selected {
+                Style::default().bg(Colors::ORANGE).fg(Colors::CHARCOAL)
+            } else if context.index % 2 == 0 {
+                Style::default().bg(Colors::CHARCOAL).fg(Colors::WHITE)
+            } else {
+                Style::default().bg(Colors::BLACK).fg(Colors::WHITE)
+            };
 
-            if context.is_selected {
-                widget.line.style = widget.line.style.bg(Color::White);
+            let block = Block::default().borders(Borders::ALL).style(style);
+            let inner = block.inner(Rect::new(0, 0, context.cross_axis_size, size));
+            let widget = SectionItem {
+                label,
+                block,
+                inner_height: inner.height,
             };
 
-            return (widget, size);
+            (widget, size)
         });
-        let list = ListView::new(builder, item_count)
-            .bg(Color::Black)
-            .block(block);
+
+        let list = ListView::new(builder, ITEMS.len())
+            .infinite_scrolling(false)
+            .scrollbar(Scrollbar::default())
+            .block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .title(" Variable Sizes "),
+            );
         list.render(area, buf, state);
     }
 }
 
-#[derive(Debug, Clone)]
-pub struct LineItem<'a> {
-    line: Line<'a>,
+struct SectionItem {
+    label: String,
+    block: Block<'static>,
+    inner_height: u16,
 }
 
-impl LineItem<'_> {
-    pub fn new(text: String) -> Self {
-        let span = Span::styled(text, Style::default().fg(Colors::TEAL));
-        let line = Line::from(span).bg(Colors::CHARCOAL);
-        Self { line }
-    }
-}
-
-impl Widget for LineItem<'_> {
+impl Widget for SectionItem {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let inner = {
-            let block = Block::default().borders(Borders::ALL);
-            block.clone().render(area, buf);
-            block.inner(area)
-        };
-
-        self.line.render(inner, buf);
+        let inner = self.block.inner(area);
+        self.block.render(area, buf);
+        if inner.height > 0 {
+            Line::from(self.label).render(inner, buf);
+        }
+        for row in 1..inner.height.min(self.inner_height) {
+            let y = inner.y + row;
+            let filler = format!("  line {}", row);
+            Line::from(filler)
+                .style(Style::default().fg(Colors::GRAY))
+                .render(Rect::new(inner.x, y, inner.width, 1), buf);
+        }
     }
 }
diff --git a/src/state.rs b/src/state.rs
@@ -21,6 +21,10 @@ pub struct ListState {
     /// True by default.
     pub(crate) infinite_scrolling: bool,
 
+    /// Scroll offset within the currently selected item. When an item is larger
+    /// than the viewport, this tracks how far we've scrolled into it.
+    pub(crate) item_scroll: u16,
+
     /// The state for the viewport. Keeps track which item to show
     /// first and how much it is truncated.
     pub(crate) view_state: ViewState,
@@ -50,6 +54,12 @@ pub(crate) struct ViewState {
 
     /// The scroll direction used during the last render.
     pub(crate) scroll_direction: ScrollDirection,
+
+    /// The viewport's main axis size from the last render.
+    pub(crate) last_main_axis_size: u16,
+
+    /// Full (untruncated) main-axis sizes of items from the last render.
+    pub(crate) total_main_axis_sizes: HashMap<usize, u16>,
 }
 
 impl Default for ViewState {
@@ -61,6 +71,8 @@ impl Default for ViewState {
             inner_area: Rect::default(),
             scroll_axis: ScrollAxis::Vertical,
             scroll_direction: ScrollDirection::Forward,
+            last_main_axis_size: 0,
+            total_main_axis_sizes: HashMap::new(),
         }
     }
 }
@@ -71,6 +83,7 @@ impl Default for ListState {
             selected: None,
             num_elements: 0,
             infinite_scrolling: true,
+            item_scroll: 0,
             view_state: ViewState::default(),
             scrollbar_state: ScrollbarState::new(0).position(0),
         }
@@ -92,6 +105,7 @@ impl ListState {
     /// Selects an item by its index.
     pub fn select(&mut self, index: Option<usize>) {
         self.selected = index;
+        self.item_scroll = 0;
         if index.is_none() {
             self.view_state.offset = 0;
             self.scrollbar_state = self.scrollbar_state.position(0);
@@ -113,6 +127,14 @@ impl ListState {
         if self.num_elements == 0 {
             return;
         }
+        // If the current item overflows the viewport, scroll within it first
+        if let Some(selected) = self.selected {
+            let overflow = self.item_overflow(selected);
+            if overflow > 0 && self.item_scroll < overflow {
+                self.item_scroll += 1;
+                return;
+            }
+        }
         let i = match self.selected {
             Some(i) => {
                 if i >= self.num_elements - 1 {
@@ -145,6 +167,11 @@ impl ListState {
         if self.num_elements == 0 {
             return;
         }
+        // If the current item overflows the viewport, scroll back within it first
+        if self.item_scroll > 0 {
+            self.item_scroll -= 1;
+            return;
+        }
         let i = match self.selected {
             Some(i) => {
                 if i == 0 {
@@ -159,6 +186,13 @@ impl ListState {
             }
             None => self.num_elements - 1,
         };
+        // If the previous item overflows the viewport, start at its bottom
+        let overflow = self.item_overflow(i);
+        if overflow > 0 {
+            self.selected = Some(i);
+            self.item_scroll = overflow;
+            return;
+        }
         self.select(Some(i));
     }
 
@@ -265,4 +299,30 @@ impl ListState {
     pub(crate) fn last_scroll_direction(&self) -> ScrollDirection {
         self.view_state.scroll_direction
     }
+
+    /// Returns how many rows/cols of the item extend beyond the viewport,
+    /// or 0 if the item fits or its size is not cached.
+    fn item_overflow(&self, index: usize) -> u16 {
+        self.view_state
+            .total_main_axis_sizes
+            .get(&index)
+            .map(|&total| total.saturating_sub(self.view_state.last_main_axis_size))
+            .unwrap_or(0)
+    }
+
+    /// Set the viewport's main axis size from the last render.
+    pub(crate) fn set_last_main_axis_size(&mut self, size: u16) {
+        self.view_state.last_main_axis_size = size;
+    }
+
+    /// Set the full (untruncated) main-axis sizes of items from the last render.
+    pub(crate) fn set_total_main_axis_sizes(&mut self, sizes: HashMap<usize, u16>) {
+        self.view_state.total_main_axis_sizes = sizes;
+    }
+
+    /// Get the scroll offset within the currently selected item.
+    #[must_use]
+    pub(crate) fn item_scroll(&self) -> u16 {
+        self.item_scroll
+    }
 }
diff --git a/src/view.rs b/src/view.rs
@@ -292,6 +292,7 @@ impl<T: Widget> StatefulWidget for ListView<'_, T> {
 
         // Resolve which items are visible and how they fit on the viewport
         let (main_axis_size, cross_axis_size) = self.scroll_axis.sizes(inner_area);
+        state.set_last_main_axis_size(main_axis_size);
         let (mut scroll_axis_pos, cross_axis_pos) = self.scroll_axis.origin(inner_area);
 
         let mut viewport = resolve_viewport(
@@ -320,12 +321,31 @@ impl<T: Widget> StatefulWidget for ListView<'_, T> {
 
         // Render each visible item and cache sizes for hit testing
         let mut cached_sizes: HashMap<usize, u16> = HashMap::new();
+        let mut cached_total_sizes: HashMap<usize, u16> = HashMap::new();
+        let viewport_end = scroll_axis_pos + main_axis_size;
+
         for i in start..end {
             let Some(element) = viewport.remove(&i) else {
                 break;
             };
 
-            let visible_size = element.visible_size();
+            cached_total_sizes.insert(i, element.main_axis_size);
+
+            // If the selected item overflows the viewport, apply item_scroll as truncation
+            let truncation = if Some(i) == state.selected
+                && state.item_scroll() > 0
+                && element.main_axis_size > main_axis_size
+            {
+                Truncation::Top(state.item_scroll())
+            } else {
+                element.truncation
+            };
+
+            let visible_size = element
+                .main_axis_size
+                .saturating_sub(truncation.value())
+                .min(viewport_end.saturating_sub(scroll_axis_pos));
+
             cached_sizes.insert(i, visible_size);
 
             render_clipped(
@@ -338,7 +358,7 @@ impl<T: Widget> StatefulWidget for ListView<'_, T> {
                 ),
                 buf,
                 element.main_axis_size,
-                &element.truncation,
+                &truncation,
                 self.style,
                 self.scroll_axis,
             );
@@ -347,6 +367,7 @@ impl<T: Widget> StatefulWidget for ListView<'_, T> {
         }
 
         state.set_visible_main_axis_sizes(cached_sizes);
+        state.set_total_main_axis_sizes(cached_total_sizes);
 
         if let Some(scrollbar) = self.scrollbar {
             scrollbar.render(area, buf, &mut state.scrollbar_state);
@@ -629,6 +650,65 @@ mod test {
         )
     }
 
+    #[test]
+    fn scroll_within_large_item() {
+        let area = Rect::new(0, 0, 5, 7);
+        let builder = ListBuilder::new(|ctx| {
+            let size = if ctx.index == 0 { 8 } else { 3 };
+            (TestItem {}, size)
+        });
+        let list = ListView::new(builder, 2);
+        let mut state = ListState::default();
+        state.select(Some(0));
+
+        // Render: shows top 7 rows
+        let mut buf = Buffer::empty(area);
+        list.render(area, &mut buf, &mut state);
+        assert_buffer_eq(
+            buf,
+            Buffer::with_lines(vec![
+                "┌───┐",
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+            ]),
+        );
+
+        // next() scrolls within and content_offset becomes 1
+        state.next();
+        assert_eq!(state.selected, Some(0));
+        assert_eq!(state.item_scroll, 1);
+
+        // Render at offset 1: shows rows 1-7
+        let mut buf = Buffer::empty(area);
+        let builder = ListBuilder::new(|ctx| {
+            let size = if ctx.index == 0 { 8 } else { 3 };
+            (TestItem {}, size)
+        });
+        let list = ListView::new(builder, 2);
+        list.render(area, &mut buf, &mut state);
+        assert_buffer_eq(
+            buf,
+            Buffer::with_lines(vec![
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+                "│   │",
+                "└───┘",
+            ]),
+        );
+
+        // next at max offset jumps to item 1
+        state.next();
+        assert_eq!(state.selected, Some(1));
+        assert_eq!(state.item_scroll, 0);
+    }
+
     fn assert_buffer_eq(actual: Buffer, expected: Buffer) {
         if actual.area != expected.area {
             panic!(
