Files
pipelines/app/lib/features/chat/conversation/chat_scroll.dart
T
alan e4c196d75b feat(app): follow streamed chat and restore its read position
Transcripts pin to the newest end while following, release on the operator's upward scroll, and offer a native Jump to latest control carrying the count of messages that arrived meanwhile. The chat destination keeps each conversation's saved position so reopening restores it.
2026-10-22 17:15:51 +01:00

126 lines
4.7 KiB
Dart

import 'dart:math' as math;
/// How close the transcript's end must be to the viewport's bottom edge before
/// the view counts as following it. A deliberate position further up is the
/// operator's own and must never be snapped back by a streamed frame.
const double chatFollowThresholdPx = 32;
/// The pixels the transcript's end still sits below the viewport's bottom edge.
///
/// Zero means the end is in view; null means the list has no content to measure.
/// A viewport that is overscrolled past the end never reports a negative
/// distance, so following is a simple threshold check.
double? chatBottomDistance({
required double maxScrollExtent,
required double pixels,
required int itemCount,
}) {
if (itemCount <= 0) return null;
return math.max(0, maxScrollExtent - pixels);
}
/// Whether the end of the transcript is at (or within the follow threshold of)
/// the viewport's bottom edge.
bool chatFollowsAt(
double? distanceFromBottom, {
required int itemCount,
double threshold = chatFollowThresholdPx,
}) =>
itemCount > 0 &&
distanceFromBottom != null &&
distanceFromBottom <= threshold;
/// Whether to offer the jump-to-latest control: only while the view is not
/// following and something is below the fold. A list that fits its viewport is
/// never offered the control, because there is nothing to return to.
bool chatShowsJumpToLatest({
required bool following,
required double? distanceFromBottom,
required int itemCount,
double threshold = chatFollowThresholdPx,
}) =>
!following &&
itemCount > 0 &&
!chatFollowsAt(
distanceFromBottom,
itemCount: itemCount,
threshold: threshold,
);
/// How many messages arrived after the operator left the bottom.
///
/// [newestAtRelease] is the id of the last message at the moment the operator
/// scrolled away. Only messages after that id count, so an older page that is
/// prepended while they read is not reported as an arrival and a delta growing
/// the held answer is not a new message. An id that no longer exists (a repair
/// replaced the transcript) reports no arrivals until the operator returns.
int chatNewMessageCount(List<String> messageIds, String? newestAtRelease) {
if (newestAtRelease == null) return 0;
final index = messageIds.lastIndexOf(newestAtRelease);
if (index < 0) return 0;
return messageIds.length - index - 1;
}
/// The jump control's words, with the web's action and the arrival count the
/// native client adds while the operator is reading above the end.
String chatJumpToLatestLabel(int newMessages) {
if (newMessages <= 0) return 'Jump to latest';
final suffix = newMessages == 1 ? '1 new message' : '$newMessages new messages';
return 'Jump to latest · $suffix';
}
/// Where a conversation's transcript is placed when it first shows.
///
/// No saved position means the operator has none of their own: open at the
/// newest content. A saved offset is kept, clamped to the current end, so a
/// conversation whose content grew or shrank while it was closed still lands on
/// a real position.
double chatRestoreOffset({
required double? savedOffset,
required double maxScrollExtent,
}) {
if (savedOffset == null) return maxScrollExtent;
return savedOffset.clamp(0.0, maxScrollExtent).toDouble();
}
/// Per-conversation transcript positions, kept while the chat list stays
/// mounted. A conversation opened again returns to the position the operator
/// left; one they never moved in opens at its newest message.
abstract interface class ChatScrollStore {
/// The offset the operator left this conversation at, or null when they never
/// scrolled away from its end.
double? read(String sessionId);
/// Records a deliberate position away from the end.
void write(String sessionId, double offset);
/// Forgets the position once the operator is following the end again.
void clear(String sessionId);
}
/// In-memory storage for the app's chat destination and for tests.
///
/// A surfaced position survives the conversation view being disposed and
/// reopened with the chat destination, but not a process restart. This native
/// client keeps no transcript position on disk and does not import the web's
/// storage keys.
class MemoryChatScrollStore implements ChatScrollStore {
final Map<String, double> _offsets = {};
/// A snapshot of the stored offsets, so a test can tell a cleared
/// conversation from one that was never moved.
Map<String, double> get entries => Map.unmodifiable(_offsets);
@override
double? read(String sessionId) => _offsets[sessionId];
@override
void write(String sessionId, double offset) {
if (!offset.isFinite || offset < 0) return;
_offsets[sessionId] = offset;
}
@override
void clear(String sessionId) => _offsets.remove(sessionId);
}