Files
pipelines/app/lib/features/chat/conversation/chat_scroll.dart
T

139 lines
5.5 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 extent, so a
/// conversation whose content grew or shrank while it was closed still lands on
/// a real position. A bottom-anchored transcript measures older rows above its
/// centre, so its offsets (and [minScrollExtent]) can be negative.
double chatRestoreOffset({
required double? savedOffset,
required double maxScrollExtent,
double minScrollExtent = 0,
}) {
if (savedOffset == null) return maxScrollExtent;
return savedOffset.clamp(minScrollExtent, maxScrollExtent).toDouble();
}
/// A saved transcript position: the scroll offset and the message id of the
/// row the transcript was split at (see `chatTranscriptAnchor`), or null for a
/// top-anchored transcript whose offset counts from its first row. An offset
/// only means something measured from the same anchor.
typedef ChatScrollPosition = ({double offset, String? anchor});
/// 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 position the operator left this conversation at, or null when they
/// never scrolled away from its end.
ChatScrollPosition? read(String sessionId);
/// Records a deliberate position away from the end.
void write(String sessionId, ChatScrollPosition position);
/// 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, ChatScrollPosition> _offsets = {};
/// A snapshot of the stored positions, so a test can tell a cleared
/// conversation from one that was never moved.
Map<String, ChatScrollPosition> get entries => Map.unmodifiable(_offsets);
@override
ChatScrollPosition? read(String sessionId) => _offsets[sessionId];
@override
void write(String sessionId, ChatScrollPosition position) {
// A top-anchored offset counts from the first row and is never negative;
// a bottom-anchored one is negative above its centre.
if (!position.offset.isFinite) return;
if (position.anchor == null && position.offset < 0) return;
_offsets[sessionId] = position;
}
@override
void clear(String sessionId) => _offsets.remove(sessionId);
}