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 the view follows the end after the operator's own scroll. /// /// A scroll toward the end follows within the threshold, so landing close to /// the end returns to it. A scroll toward older rows releases the end unless it /// is still exactly there: a wheel or trackpad scroll arrives as separate small /// ticks, and treating each one as "close enough" would pin the view. bool chatFollowsAfterScroll( double? distanceFromBottom, { required int itemCount, required bool towardOlder, double threshold = chatFollowThresholdPx, }) => chatFollowsAt( distanceFromBottom, itemCount: itemCount, threshold: towardOlder ? chatAtEndTolerancePx : threshold, ); /// How far from the end still counts as at the end, for rounding only. const double chatAtEndTolerancePx = 0.5; /// 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 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 _offsets = {}; /// A snapshot of the stored positions, so a test can tell a cleared /// conversation from one that was never moved. Map 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); }