Skip to content

feat(tv): scroll focused scrollbar into view - #2338

Open
usmanvrtx wants to merge 2 commits into
android_TV_implementationfrom
feat/tv-focus-scroll-into-view
Open

feat(tv): scroll focused scrollbar into view#2338
usmanvrtx wants to merge 2 commits into
android_TV_implementationfrom
feat/tv-focus-scroll-into-view

Conversation

@usmanvrtx

Copy link
Copy Markdown
Contributor

Description

This PR ensures a focused scrollbar is always revealed within its enclosing vertical scrollable on TV. Previously, when the scrollbar gained focus while positioned outside the visible viewport of a parent scrollable (e.g. a long ListView), it could remain hidden off-screen, making D-pad navigation confusing.

The change adds a reusable scroll-into-view helper that scrolls only the nearest vertical scrollable ancestor, so vertical positioning is fixed without jittering horizontal navigation.

Related Issue

N/A

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Refactoring (no functional changes)

What Has Changed

  • Added modules/ensemble/lib/framework/tv/tv_focus_scroll.dart with:
    • findNearestVerticalScrollable(BuildContext) — finds the nearest vertical Scrollable ancestor
    • scrollWidgetIntoView(BuildContext, {verticalPadding, animationDurationMs, curve}) — scrolls only the nearest vertical scrollable so a widget's render box is fully visible, using padding from the viewport edges and clamping to valid scroll extents
    • Configurable constants: kTVScrollAnimationDurationMs, kTVVerticalScrollPadding, kTVScrollThreshold
  • Updated TVScrollbarWidget in tv_scrollbar_widget.dart to call scrollWidgetIntoView(context) when the scrollbar gains focus, via a post-frame callback that re-checks _isFocused so stale callbacks are ignored
  • This matches the same scroll-into-view rule already implemented for regular focusable widgets in box_wrapper.dart

How to Test

  1. Run the relevant TV tests (if any): flutter test modules/ensemble/test/widget/tv_scrollbar_widget_test.dart
  2. On a TV/emulator, focus a scrollbar whose parent is a long vertical scrollable — the scrollbar should be scrolled into view when focused
  3. Move focus to an item that is fully visible — no scroll should occur (no jitter)
  4. Navigate horizontally — vertical scroll position should remain unchanged
  5. Verify regular focus navigation still works as before

Screenshots / Videos

N/A

Checklist

  • I have run flutter analyze and addressed any new warnings
  • I have run flutter test and all tests pass
  • I have tested my changes on the relevant platform(s)
  • I have updated documentation if needed
  • My changes do not introduce new warnings or errors

Add TV scroll-into-view logic that reveals the focused scrollbar within its
nearest vertical scrollable ancestor. Only affects vertical scrolling so
horizontal navigation doesn't jitter.
@usmanvrtx
usmanvrtx requested a review from TheNoumanDev August 7, 2026 21:30
@usmanvrtx usmanvrtx self-assigned this Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants