Expose horizontal chat overflow with native scrollbars and keyboard controls

This commit is contained in:
2026-11-07 20:35:13 +00:00
parent 5ddd52f817
commit 004979ccd0
6 changed files with 432 additions and 4 deletions
@@ -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<ChatHorizontalViewport> createState() => _ChatHorizontalViewportState();
}
class _ChatHorizontalViewportState extends State<ChatHorizontalViewport> {
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<ScrollMetricsNotification>(
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),
),
),
],
),
),
),
),
],
),
),
),
),
);
}
}
@@ -193,6 +193,7 @@ class _ChatMarkdownViewState extends State<ChatMarkdownView> {
);
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<ChatMarkdownView> {
child: Padding(
padding: const EdgeInsets.all(12),
child: ChatTranscriptHorizontalScrollView(
label: 'code block',
child: Text(
code,
style: const TextStyle(fontFamily: appMonospaceFamily),
@@ -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<ChatTranscriptHorizontalScrollView> 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);
}
@@ -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.
+31
View File
@@ -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.
@@ -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<CupertinoScrollbar>(find.byType(CupertinoScrollbar))
.controller!
: tester.widget<Scrollbar>(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<CupertinoScrollbar>(
find.byType(CupertinoScrollbar),
)
.thumbVisibility
: tester
.widget<Scrollbar>(find.byType(Scrollbar))
.thumbVisibility,
isTrue,
);
expect(find.byIcon(Icons.arrow_forward), findsOneWidget);
final focus = tester
.widgetList<Focus>(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<Icon>(find.byIcon(Icons.arrow_back)).textDirection,
TextDirection.ltr,
);
final controller = _controller(tester, false);
final focus = tester
.widgetList<Focus>(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);
});
}