refactor: extract _scrollbar_metrics from _FullscreenPeek render method

The scrollbar geometry calculation (thumb position, size, visibility)
was inlined in the 75-line __rich_console__ method. Extract it into a
pure function so the render method is easier to follow and the math
gains dedicated test coverage.

Co-authored-by: Ralphify <noreply@ralphify.co>

Author: 2 people

src/ralphify/_console_emitter.py

@@ -575,6 +575,43 @@ def _build_footer(self) -> Table:
 _FULLSCREEN_MIN_VISIBLE = 5
 
 
+class _ScrollbarMetrics:
+    """Pure-data result of scrollbar geometry calculation.
+
+    ``show`` is ``False`` when the buffer fits in the viewport and no
+    scrollbar should be rendered.  ``thumb_start`` and ``thumb_size``
+    are row indices within the viewport, valid only when ``show`` is
+    ``True``.
+    """
+
+    __slots__ = ("show", "thumb_start", "thumb_size")
+
+    def __init__(self, show: bool, thumb_start: int, thumb_size: int) -> None:
+        self.show = show
+        self.thumb_start = thumb_start
+        self.thumb_size = thumb_size
+
+
+def _scrollbar_metrics(total: int, visible: int, offset: int) -> _ScrollbarMetrics:
+    """Compute scrollbar position and size for the fullscreen peek view.
+
+    *total* is the number of buffered lines, *visible* the viewport
+    height, and *offset* how many lines are hidden below the viewport
+    (0 = following the tail).
+
+    Returns a :class:`_ScrollbarMetrics` with ``show=False`` when the
+    buffer fits within the viewport.
+    """
+    if total <= visible:
+        return _ScrollbarMetrics(show=False, thumb_start=0, thumb_size=0)
+    thumb_size = max(1, visible * visible // total)
+    max_off = max(total - visible, 1)
+    frac = 1.0 - (offset / max_off)
+    track_space = visible - thumb_size
+    thumb_start = int(frac * track_space)
+    return _ScrollbarMetrics(show=True, thumb_start=thumb_start, thumb_size=thumb_size)
+
+
 class _FullscreenPeek:
     """Scrollable alt-screen view of the activity buffer.
 
@@ -674,16 +711,7 @@ def __rich_console__(
         start = max(0, end - visible)
         window = lines[start:end]
 
-        # Scrollbar metrics
-        show_scrollbar = total > visible
-        thumb_start = 0
-        thumb_size = visible
-        if show_scrollbar:
-            thumb_size = max(1, visible * visible // total)
-            max_off_val = max(total - visible, 1)
-            frac = 1.0 - (self._offset / max_off_val)
-            track_space = visible - thumb_size
-            thumb_start = int(frac * track_space)
+        sb = _scrollbar_metrics(total, visible, self._offset)
 
         rows: list[Any] = []
         rows.append(self._build_header(total, visible))
@@ -692,7 +720,7 @@ def __rich_console__(
         # Content area with optional scrollbar column
         content = Table.grid(expand=True)
         content.add_column(ratio=1, no_wrap=True, overflow="ellipsis")
-        if show_scrollbar:
+        if sb.show:
             content.add_column(width=1, no_wrap=True)
 
         for i in range(visible):
@@ -702,8 +730,8 @@ def __rich_console__(
                 line.overflow = "ellipsis"
             else:
                 line = Text("")
-            if show_scrollbar:
-                in_thumb = thumb_start <= i < thumb_start + thumb_size
+            if sb.show:
+                in_thumb = sb.thumb_start <= i < sb.thumb_start + sb.thumb_size
                 bar = Text(
                     "█" if in_thumb else "│",
                     style=_brand.PURPLE if in_thumb else "dim",
@@ -712,7 +740,7 @@ def __rich_console__(
             else:
                 content.add_row(line)
 
-        if not window and not show_scrollbar:
+        if not window and not sb.show:
             # Replace the empty grid with a waiting message
             rows.append(Text("  (waiting for activity…)", style="dim italic"))
             for _ in range(max(0, visible - 1)):

tests/test_console_emitter.py

@@ -15,6 +15,7 @@
     _format_run_info,
     _format_summary,
     _is_claude_command,
+    _scrollbar_metrics,
     _shorten_path,
 )
 from ralphify._events import Event, EventType
@@ -1618,6 +1619,61 @@ def test_empty_buffer_shows_waiting_message(self):
         assert "waiting for activity" in console.export_text()
 
 
+class TestScrollbarMetrics:
+    """Unit tests for _scrollbar_metrics pure calculation."""
+
+    def test_no_scrollbar_when_buffer_fits(self):
+        sb = _scrollbar_metrics(total=10, visible=20, offset=0)
+        assert sb.show is False
+
+    def test_no_scrollbar_when_exact_fit(self):
+        sb = _scrollbar_metrics(total=20, visible=20, offset=0)
+        assert sb.show is False
+
+    def test_scrollbar_shown_when_buffer_exceeds_viewport(self):
+        sb = _scrollbar_metrics(total=100, visible=20, offset=0)
+        assert sb.show is True
+
+    def test_thumb_at_bottom_when_offset_zero(self):
+        sb = _scrollbar_metrics(total=100, visible=20, offset=0)
+        assert sb.show is True
+        # offset=0 means following tail; thumb should be at the bottom
+        # of the track (frac=1.0 → thumb_start = track_space).
+        track_space = 20 - sb.thumb_size
+        assert sb.thumb_start == track_space
+
+    def test_thumb_at_top_when_offset_at_max(self):
+        total, visible = 100, 20
+        max_offset = total - visible  # 80
+        sb = _scrollbar_metrics(total=total, visible=visible, offset=max_offset)
+        assert sb.show is True
+        assert sb.thumb_start == 0
+
+    def test_thumb_size_proportional_to_viewport(self):
+        sb = _scrollbar_metrics(total=100, visible=20, offset=0)
+        # thumb_size = max(1, 20*20 // 100) = 4
+        assert sb.thumb_size == 4
+
+    def test_thumb_size_minimum_one(self):
+        sb = _scrollbar_metrics(total=10000, visible=10, offset=0)
+        # 10*10 // 10000 = 0 → clamped to 1
+        assert sb.thumb_size == 1
+
+    def test_midpoint_offset(self):
+        total, visible = 200, 40
+        max_offset = total - visible  # 160
+        mid_offset = max_offset // 2  # 80
+        sb = _scrollbar_metrics(total=total, visible=visible, offset=mid_offset)
+        assert sb.show is True
+        # Thumb should be roughly in the middle of the track
+        track_space = visible - sb.thumb_size
+        assert 0 < sb.thumb_start < track_space
+
+    def test_empty_buffer(self):
+        sb = _scrollbar_metrics(total=0, visible=20, offset=0)
+        assert sb.show is False
+
+
 class TestFullscreenPeekEmitter:
     """Integration tests for fullscreen peek on ConsoleEmitter."""