From 004979ccd063560625a82e8e3a4c82c37f6c3b87 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 7 Nov 2026 20:35:13 +0000 Subject: [PATCH] Expose horizontal chat overflow with native scrollbars and keyboard controls --- .../transcript/chat_horizontal_viewport.dart | 184 ++++++++++++++++ .../ui/transcript/chat_markdown_view.dart | 2 + .../transcript/chat_transcript_selection.dart | 14 +- .../ui/layout/wheel_scroll_forwarding.dart | 4 +- app/notes/chat-horizontal-overflow.md | 31 +++ .../chat_horizontal_viewport_test.dart | 201 ++++++++++++++++++ 6 files changed, 432 insertions(+), 4 deletions(-) create mode 100644 app/lib/features/chat/ui/transcript/chat_horizontal_viewport.dart create mode 100644 app/notes/chat-horizontal-overflow.md create mode 100644 app/test/features/chat/ui/transcript/chat_horizontal_viewport_test.dart diff --git a/app/lib/features/chat/ui/transcript/chat_horizontal_viewport.dart b/app/lib/features/chat/ui/transcript/chat_horizontal_viewport.dart new file mode 100644 index 00000000..b931f92d --- /dev/null +++ b/app/lib/features/chat/ui/transcript/chat_horizontal_viewport.dart @@ -0,0 +1,184 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import '../../../../ui/adaptive/host.dart'; +import '../../../../ui/layout/wheel_scroll_forwarding.dart'; + +/// Native, persistent overflow affordances for a code block or table. The +/// footer is outside the selectable document and never overlays its content. +class ChatHorizontalViewport extends StatefulWidget { + const ChatHorizontalViewport({ + super.key, + required this.child, + this.label = 'content', + }); + final Widget child; + final String label; + @override + State createState() => _ChatHorizontalViewportState(); +} + +class _ChatHorizontalViewportState extends State { + final _controller = ScrollController(); + final _focus = FocusNode(debugLabel: 'Horizontal chat content'); + bool _overflow = false, _left = false, _right = false, _focused = false; + bool _scheduled = false; + + @override + void initState() { + super.initState(); + _controller.addListener(_scheduleMetrics); + } + + void _scheduleMetrics() { + if (_scheduled) return; + _scheduled = true; + WidgetsBinding.instance.addPostFrameCallback((_) { + _scheduled = false; + if (!mounted || !_controller.hasClients) return; + final p = _controller.position; + final overflow = p.maxScrollExtent - p.minScrollExtent > .5; + final reverse = axisDirectionIsReversed(p.axisDirection); + final before = overflow && p.pixels > p.minScrollExtent + .5; + final after = overflow && p.pixels < p.maxScrollExtent - .5; + final left = reverse ? after : before; + final right = reverse ? before : after; + if (_overflow == overflow && _left == left && _right == right) return; + setState(() { + _overflow = overflow; + _left = left; + _right = right; + }); + }); + } + + void _move(double physicalDelta) { + if (!_controller.hasClients) return; + final p = _controller.position; + final delta = axisDirectionIsReversed(p.axisDirection) + ? -physicalDelta + : physicalDelta; + _controller.jumpTo( + (p.pixels + delta).clamp(p.minScrollExtent, p.maxScrollExtent), + ); + } + + KeyEventResult _key(FocusNode node, KeyEvent event) { + if (!_focus.hasPrimaryFocus || + !_overflow || + (event is! KeyDownEvent && event is! KeyRepeatEvent) || + HardwareKeyboard.instance.isShiftPressed || + HardwareKeyboard.instance.isControlPressed || + HardwareKeyboard.instance.isMetaPressed || + HardwareKeyboard.instance.isAltPressed) { + return KeyEventResult.ignored; + } + if (event.logicalKey == LogicalKeyboardKey.arrowLeft) { + _move(-80); + } else if (event.logicalKey == LogicalKeyboardKey.arrowRight) { + _move(80); + } else { + return KeyEventResult.ignored; + } + return KeyEventResult.handled; + } + + @override + void dispose() { + _controller.removeListener(_scheduleMetrics); + _controller.dispose(); + _focus.dispose(); + super.dispose(); + } + + @override + Widget build(BuildContext context) { + final cupertino = usesCupertinoHost(context); + final color = cupertino + ? CupertinoColors.secondaryLabel.resolveFrom(context) + : Theme.of(context).colorScheme.onSurfaceVariant; + final focusColor = cupertino + ? CupertinoTheme.of(context).primaryColor + : Theme.of(context).colorScheme.primary; + final view = Padding( + padding: EdgeInsets.only(bottom: _overflow ? 12 : 0), + child: HorizontalScrollView(controller: _controller, child: widget.child), + ); + final scrollbar = cupertino + ? CupertinoScrollbar( + controller: _controller, + thumbVisibility: _overflow, + child: view, + ) + : Scrollbar( + controller: _controller, + thumbVisibility: _overflow, + trackVisibility: _overflow, + child: view, + ); + return NotificationListener( + onNotification: (notification) { + if (notification.metrics.axis == Axis.horizontal) _scheduleMetrics(); + return false; + }, + child: Focus( + focusNode: _focus, + canRequestFocus: _overflow, + onFocusChange: (value) => setState(() => _focused = value), + onKeyEvent: _key, + child: Semantics( + label: _overflow ? 'Horizontally scrollable ${widget.label}' : null, + hint: _overflow + ? 'Swipe sideways or focus and use the left and right arrow keys.' + : null, + onScrollLeft: _left ? () => _move(-80) : null, + onScrollRight: _right ? () => _move(80) : null, + child: DecoratedBox( + position: DecorationPosition.foreground, + decoration: BoxDecoration( + border: Border.all( + color: _focused ? focusColor : Colors.transparent, + ), + ), + child: Column( + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + scrollbar, + if (_overflow) + SelectionContainer.disabled( + child: ExcludeSemantics( + child: Padding( + padding: const EdgeInsets.only(top: 4), + child: Row( + children: [ + Icon( + _left && _right + ? Icons.swap_horiz + : _left + ? Icons.arrow_back + : Icons.arrow_forward, + size: 16, + textDirection: TextDirection.ltr, + color: color, + ), + const SizedBox(width: 4), + Flexible( + child: Text( + 'Scroll horizontally', + style: TextStyle(color: color), + ), + ), + ], + ), + ), + ), + ), + ], + ), + ), + ), + ), + ); + } +} diff --git a/app/lib/features/chat/ui/transcript/chat_markdown_view.dart b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart index a29c5634..ee3a9409 100644 --- a/app/lib/features/chat/ui/transcript/chat_markdown_view.dart +++ b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart @@ -193,6 +193,7 @@ class _ChatMarkdownViewState extends State { ); case MarkdownTable(header: final header, rows: final rows): return ChatTranscriptHorizontalScrollView( + label: 'table', child: Table( defaultColumnWidth: const IntrinsicColumnWidth(), border: TableBorder.all(color: _dividerColor(context, cupertino)), @@ -231,6 +232,7 @@ class _ChatMarkdownViewState extends State { child: Padding( padding: const EdgeInsets.all(12), child: ChatTranscriptHorizontalScrollView( + label: 'code block', child: Text( code, style: const TextStyle(fontFamily: appMonospaceFamily), diff --git a/app/lib/features/chat/ui/transcript/chat_transcript_selection.dart b/app/lib/features/chat/ui/transcript/chat_transcript_selection.dart index 9d695ff4..13ef891a 100644 --- a/app/lib/features/chat/ui/transcript/chat_transcript_selection.dart +++ b/app/lib/features/chat/ui/transcript/chat_transcript_selection.dart @@ -5,7 +5,7 @@ import 'package:flutter/services.dart'; import 'package:flutter/rendering.dart'; import '../../../../ui/adaptive/host.dart'; -import '../../../../ui/layout/wheel_scroll_forwarding.dart'; +import 'chat_horizontal_viewport.dart'; /// The selection controller shared by all link spans in one transcript. /// @@ -114,8 +114,13 @@ class _ChatTranscriptSelectionAreaState /// mean after, not before. Give the vertical position priority outside its /// height, while keeping normal horizontal selection and scrolling inside. class ChatTranscriptHorizontalScrollView extends StatefulWidget { - const ChatTranscriptHorizontalScrollView({super.key, required this.child}); + const ChatTranscriptHorizontalScrollView({ + super.key, + required this.child, + this.label = 'content', + }); final Widget child; + final String label; @override State createState() => @@ -134,7 +139,10 @@ class _ChatTranscriptHorizontalScrollViewState @override Widget build(BuildContext context) { - final view = HorizontalScrollView(child: widget.child); + final view = ChatHorizontalViewport( + label: widget.label, + child: widget.child, + ); if (ChatTranscriptSelectionScope.maybeOf(context) == null) return view; return SelectionContainer(delegate: _delegate, child: view); } diff --git a/app/lib/ui/layout/wheel_scroll_forwarding.dart b/app/lib/ui/layout/wheel_scroll_forwarding.dart index e3db313c..a0ec1775 100644 --- a/app/lib/ui/layout/wheel_scroll_forwarding.dart +++ b/app/lib/ui/layout/wheel_scroll_forwarding.dart @@ -59,13 +59,15 @@ bool isSidewaysWheel(BuildContext context, PointerScrollEvent event) { /// list. A mostly sideways gesture, or Shift + wheel, scrolls this box; touch /// drags are unchanged (the gesture arena already splits them by axis). class HorizontalScrollView extends StatelessWidget { - const HorizontalScrollView({super.key, required this.child}); + const HorizontalScrollView({super.key, required this.child, this.controller}); final Widget child; + final ScrollController? controller; @override Widget build(BuildContext context) => SingleChildScrollView( scrollDirection: Axis.horizontal, + controller: controller, // Below the horizontal scrollable, so this claim comes before its own. // Translucent: the gaps between a table's cells or a block's lines hit no // child, yet the scrollable around them still claims the event there. diff --git a/app/notes/chat-horizontal-overflow.md b/app/notes/chat-horizontal-overflow.md new file mode 100644 index 00000000..481f5f51 --- /dev/null +++ b/app/notes/chat-horizontal-overflow.md @@ -0,0 +1,31 @@ +# Chat code and table overflow affordances + +Code blocks and markdown tables now show an explicit 'Scroll horizontally' +footer with a physical direction arrow and a persistent native scrollbar only +when content actually overflows. The thumb has its own gutter and the cue sits +below the viewport; neither overlays code/table text. The cue is excluded from +selection, so copying a transcript never includes UI instructions. + +The viewport retains its own ScrollController, and existing vertical wheel / +trackpad forwarding is unchanged. Touch dragging and native scrollbar dragging +still work. Keyboard users can focus the overflowing viewport, see a theme +focus outline and use unmodified left/right arrows. Selection-focused arrow +keys and modifier chords are left alone. Screen readers get content-specific +labels ('Horizontally scrollable code block' / '... table') and directional +scroll actions. Indicators update at both endpoints, including RTL. Short +content has no extra cue or gutter. + +Changed: transcript/chat_horizontal_viewport.dart, chat_transcript_selection.dart, +chat_markdown_view.dart and an optional controller on the shared +ui/layout/wheel_scroll_forwarding.dart HorizontalScrollView. + +181 transcript, selection, copy/hover, wheel-forwarding and new affordance tests +passed (/tmp/memwatch/out.Ut4aN1, peak1457MB,12s). New tests cover Material and +Cupertino light/dark at2x text, no overflow, endpoint changes, keyboard focus, +RTL, retained offsets, vertical wheel forwarding, horizontal touch and code/table +semantics. Analyzer clean (flutter-analyze.jBzTTK). One initial gesture test used +the center of unconstrained text beyond the viewport; corrected to a visible +viewport point before the successful run. + +Integrated browser capture/review is with the parent task; no production chats, +shared services or physical devices were touched by this lane. diff --git a/app/test/features/chat/ui/transcript/chat_horizontal_viewport_test.dart b/app/test/features/chat/ui/transcript/chat_horizontal_viewport_test.dart new file mode 100644 index 00000000..4a34a954 --- /dev/null +++ b/app/test/features/chat/ui/transcript/chat_horizontal_viewport_test.dart @@ -0,0 +1,201 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/chat/ui/transcript/chat_horizontal_viewport.dart'; +import 'package:pipelines_app/features/chat/ui/transcript/chat_markdown_view.dart'; + +Widget _host({ + bool cupertino = false, + Brightness brightness = Brightness.dark, + TextDirection direction = TextDirection.ltr, + double contentWidth = 900, + double width = 260, + ScrollController? vertical, + Widget? child, +}) { + final body = Directionality( + textDirection: direction, + child: MediaQuery( + data: const MediaQueryData(textScaler: TextScaler.linear(2)), + child: SingleChildScrollView( + controller: vertical, + child: Column( + children: [ + SizedBox( + width: width, + child: + child ?? + ChatHorizontalViewport( + child: SizedBox( + width: contentWidth, + height: 80, + child: const Text('Readable content'), + ), + ), + ), + const SizedBox(height: 1200), + ], + ), + ), + ), + ); + return cupertino + ? CupertinoApp( + theme: CupertinoThemeData(brightness: brightness), + home: CupertinoPageScaffold(child: body), + ) + : MaterialApp( + theme: ThemeData(brightness: brightness), + home: Scaffold(body: body), + ); +} + +ScrollController _controller(WidgetTester tester, bool cupertino) => cupertino + ? tester + .widget(find.byType(CupertinoScrollbar)) + .controller! + : tester.widget(find.byType(Scrollbar)).controller!; + +void main() { + for (final cupertino in [false, true]) { + for (final brightness in Brightness.values) { + testWidgets( + 'native overflow affordance, endpoints and keyboard $cupertino $brightness', + (tester) async { + await tester.pumpWidget( + _host(cupertino: cupertino, brightness: brightness), + ); + await tester.pumpAndSettle(); + expect(find.text('Scroll horizontally'), findsOneWidget); + final controller = _controller(tester, cupertino); + expect(controller.position.maxScrollExtent, 640); + expect( + cupertino + ? tester + .widget( + find.byType(CupertinoScrollbar), + ) + .thumbVisibility + : tester + .widget(find.byType(Scrollbar)) + .thumbVisibility, + isTrue, + ); + expect(find.byIcon(Icons.arrow_forward), findsOneWidget); + final focus = tester + .widgetList(find.byType(Focus)) + .firstWhere( + (f) => f.focusNode?.debugLabel == 'Horizontal chat content', + ); + focus.focusNode!.requestFocus(); + await tester.pump(); + await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight); + await tester.pumpAndSettle(); + expect(controller.offset, 80); + expect(find.byIcon(Icons.swap_horiz), findsOneWidget); + controller.jumpTo(controller.position.maxScrollExtent); + await tester.pumpAndSettle(); + expect(find.byIcon(Icons.arrow_back), findsOneWidget); + await tester.pumpWidget( + _host( + cupertino: cupertino, + brightness: brightness, + contentWidth: 120, + ), + ); + await tester.pumpAndSettle(); + expect(find.text('Scroll horizontally'), findsNothing); + expect(tester.takeException(), isNull); + }, + ); + } + } + + testWidgets( + 'RTL arrows describe physical direction and offset survives rebuild', + (tester) async { + await tester.pumpWidget(_host(direction: TextDirection.rtl)); + await tester.pumpAndSettle(); + expect(find.byIcon(Icons.arrow_back), findsOneWidget); + expect( + tester.widget(find.byIcon(Icons.arrow_back)).textDirection, + TextDirection.ltr, + ); + final controller = _controller(tester, false); + final focus = tester + .widgetList(find.byType(Focus)) + .firstWhere( + (f) => f.focusNode?.debugLabel == 'Horizontal chat content', + ); + focus.focusNode!.requestFocus(); + await tester.pump(); + await tester.sendKeyEvent(LogicalKeyboardKey.arrowLeft); + await tester.pumpAndSettle(); + expect(controller.offset, 80); + await tester.pumpWidget( + _host(direction: TextDirection.rtl, brightness: Brightness.light), + ); + await tester.pumpAndSettle(); + expect(_controller(tester, false).offset, 80); + expect(tester.takeException(), isNull); + }, + ); + + testWidgets( + 'vertical wheel over overflowing content reaches parent and touch scrolls sideways', + (tester) async { + final vertical = ScrollController(); + await tester.pumpWidget(_host(vertical: vertical)); + await tester.pumpAndSettle(); + final controller = _controller(tester, false); + await tester.sendEventToBinding( + PointerScrollEvent( + position: + tester.getTopLeft(find.byType(ChatHorizontalViewport)) + + const Offset(80, 30), + scrollDelta: const Offset(0, 120), + kind: PointerDeviceKind.mouse, + ), + ); + await tester.pumpAndSettle(); + expect(vertical.offset, greaterThan(0)); + vertical.jumpTo(0); + await tester.pump(); + await tester.dragFrom( + tester.getTopLeft(find.byType(ChatHorizontalViewport)) + + const Offset(180, 30), + const Offset(-120, 0), + ); + await tester.pumpAndSettle(); + expect(controller.offset, greaterThan(0)); + await tester.pumpWidget(const SizedBox()); + vertical.dispose(); + }, + ); + + testWidgets('code and table labels identify the scrollable region', ( + tester, + ) async { + await tester.pumpWidget( + _host( + child: const ChatMarkdownView( + text: + '```\nvery_long_identifier_very_long_identifier_very_long_identifier\n```\n\n| Heading one | Heading two | Heading three |\n| --- | --- | --- |\n| alpha alpha alpha | beta beta beta | gamma gamma gamma |', + ), + ), + ); + await tester.pumpAndSettle(); + expect( + find.bySemanticsLabel('Horizontally scrollable code block'), + findsOneWidget, + ); + expect( + find.bySemanticsLabel('Horizontally scrollable table'), + findsOneWidget, + ); + expect(find.text('Scroll horizontally'), findsNWidgets(2)); + expect(tester.takeException(), isNull); + }); +}