feat: bounded message window for centered Jump to Message (#7388)

Author: diegolmello

UBIQUITOUS_LANGUAGE.md

@@ -36,6 +36,22 @@
 | **Pinned**  | Message flagged as important and pinned to the Room by a user        | Bookmarked       |
 | **Starred** | Message bookmarked by the current user for personal reference        | Saved            |
 
+## Message Loading
+
+| Term                | Definition                                                                                                                         | Aliases to avoid       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| **Message Window**  | The contiguous range of Messages the Room view currently observes and renders (distinct from what is synced to the database)       | Page, feed             |
+| **Live Tail**       | The newest end of a Room's Messages; a Message Window at the Live Tail receives new Messages automatically                         | Bottom, latest         |
+| **Live Window**     | A Message Window whose newest edge is the Live Tail — grows older as you scroll up and follows new Messages at the bottom          | —                      |
+| **Anchored Window** | A Message Window pinned around a Jump to Message target instead of the Live Tail; deliberately does not follow new Messages        | —                      |
+| **Chunk**           | A contiguous run of Messages synced from the server into the local database, bracketed by Loader Rows where more exists            | Batch, page            |
+| **Gap**             | A region between two Chunks where Messages exist on the server but not yet locally; represented by a Loader Row                    | Hole                   |
+| **Loader Row**      | A placeholder Message record marking a Gap; becoming visible triggers a server fetch                                               | Load-more, spinner row |
+| **Older Loader**    | A Loader Row marking older Messages (types `MORE`, `PREVIOUS_CHUNK`) — resolving it fetches Messages before it                     | Load previous          |
+| **Newer Loader**    | A Loader Row marking newer Messages (type `NEXT_CHUNK`) — resolving it fetches Messages after it                                   | Load next              |
+| **Room History**    | Older Messages of a Room fetched on demand from the server (distinct from **Server History**)                                      | Message history        |
+| **Jump to Message** | Re-position the Room view onto a target Message that may be far from the Live Tail or not yet synced — fetches a surrounding Chunk | Scroll to message      |
+
 ## Users & Roles
 
 | Term            | Definition                                                                         | Aliases to avoid        |
@@ -130,6 +146,9 @@
 - An **Omnichannel Room** connects exactly one **Visitor** with zero or one **Agents** (via **Served By**)
 - An **Agent** belongs to one or more **Departments**
 - An **Inquiry** becomes an **Omnichannel Room** when picked up by an **Agent**
+- A **Room** view shows a **Live Window** by default; a **Jump to Message** replaces it with an **Anchored Window**
+- A **Gap** is bracketed by **Loader Rows**; resolving a Loader Row fetches a **Chunk** and may shrink or close the Gap
+- **Jump to Message** fetches a **Chunk** centered on the target (`loadSurroundingMessages`), bracketed by an **Older Loader** and a **Newer Loader** when more Messages exist on either side
 
 ## Example dialogue
 
@@ -147,3 +166,6 @@
 - **"Account"** is sometimes used loosely to mean either **User** (the identity) or **Server** (the connected instance). These are distinct: a **User** authenticates on a **Server**.
 - **"Channel"** in everyday speech can mean any Room, but in domain terms it strictly means a public Room (type `'c'`). A private Room is a **Group** (type `'p'`).
 - **"Forward"** in omnichannel context means **Transfer** (reassigning a room to another agent/department). The codebase uses both `forwardRoom` and "transfer" — prefer **Transfer** as the domain term.
+- **"History"** is overloaded: **Server History** is the recent-Servers reconnection list; **Room History** is older Messages fetched on demand. The action `roomHistoryRequest` and saga `ROOM.HISTORY_REQUEST` refer to **Room History**.
+- **"Window"** is used metaphorically in the Subscriptions dialogue ("a Subscription is the user's window into it"); a **Message Window** is the concrete observed Message range in the Room view. Disambiguate when both could be meant.
+- **"Load more"** is directional: older Messages are an **Older Loader** (`MORE`/`PREVIOUS_CHUNK`), newer Messages are a **Newer Loader** (`NEXT_CHUNK`). Avoid bare "load more".

app/lib/dayjs/index.ts

@@ -37,4 +37,8 @@ dayjs.extend(calendar);
 dayjs.extend(relativeTime);
 dayjs.extend(localizedFormat);
 
+// WatermelonDB hands a message `ts` back as Date, ms number, or ISO string depending on the read path;
+// dayjs parses all three where Number(ts) / new Date(ts) each NaN on one. Normalize to ms since epoch.
+export const tsToMs = (ts: Date | number | string): number => dayjs(ts).valueOf();
+
 export default dayjs;

app/views/RoomView/List/components/List.tsx

@@ -23,19 +23,22 @@ const styles = StyleSheet.create({
 	}
 });
 
-const List = ({ listRef, jumpToBottom, ...props }: IListProps) => {
-	const [visible, setVisible] = useState(false);
+const List = ({ listRef, jumpToBottom, isAnchored, ...props }: IListProps) => {
+	const [scrolledPastLimit, setScrolledPastLimit] = useState(false);
 	const { isAutocompleteVisible } = useRoomContext();
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: event => {
 			if (event.contentOffset.y > SCROLL_LIMIT) {
-				scheduleOnRN(setVisible, true);
+				scheduleOnRN(setScrolledPastLimit, true);
 			} else {
-				scheduleOnRN(setVisible, false);
+				scheduleOnRN(setScrolledPastLimit, false);
 			}
 		}
 	});
 
+	// Anchored window: loaded rows' bottom edge isn't the Live Tail, so force the FAB visible to keep a path back to live.
+	const visible = scrolledPastLimit || !!isAnchored;
+
 	const isScreenReaderEnabled = useIsScreenReaderEnabled();
 
 	const renderScrollComponent = !isIOS && (isScreenReaderEnabled || isExternalKeyboardConnected());
@@ -57,7 +60,7 @@ const List = ({ listRef, jumpToBottom, ...props }: IListProps) => {
 						: undefined
 				}
 				removeClippedSubviews={isIOS}
-				initialNumToRender={7}
+				initialNumToRender={20}
 				onEndReachedThreshold={0.5}
 				maxToRenderPerBatch={5}
 				windowSize={10}

app/views/RoomView/List/constants.ts

@@ -1,10 +1,6 @@
 export const QUERY_SIZE = 50;
 export const MAX_AUTO_LOADS = 10;
 
-export const VIEWABILITY_CONFIG = {
-	itemVisiblePercentThreshold: 10
-};
-
 export const SCROLL_LIMIT = 200;
 
 export const EDGE_DISTANCE = 15;

app/views/RoomView/List/definitions.ts

@@ -11,11 +11,19 @@ export type TMessagesIdsRef = RefObject<string[]>;
 export interface IListProps extends FlatListProps<TAnyMessageModel> {
 	listRef: TListRef;
 	jumpToBottom: () => void;
+	// Anchored Window: loaded rows' bottom isn't the Live Tail, so the scroll-offset
+	// heuristic alone would hide the jump-to-bottom FAB. Keep it visible so "back to live" stays one tap.
+	isAnchored?: boolean;
 }
 
 export interface IListContainerRef {
-	jumpToMessage: (messageId: string) => Promise<void>;
+	// highTs: upper ts bound (ms) for an Anchored Window on the target's Chunk; null/undefined keeps a
+	// Live Window (contiguous / thread / local targets).
+	jumpToMessage: (messageId: string, highTs?: number | null) => Promise<void>;
 	cancelJumpToMessage: () => void;
+	// True when messageId is in the rendered window, so the orchestration skips re-anchoring for an
+	// already-visible target (a quoted reply nearby scrolls in place, Live Tail intact).
+	isMessageInWindow: (messageId: string) => boolean;
 }
 
 export interface IListContainerProps {

app/views/RoomView/List/hooks/useMessages.test.tsx

@@ -67,6 +67,12 @@ describe('useMessages', () => {
 	let emitVisibleRows: ((rows: TAnyMessageModel[]) => void) | null;
 	let queryCalls: unknown[][];
 	let unsubscribeSpies: jest.Mock[];
+	// Rows served to the targeted one-shot read used by the rejoin raise (the region above the current
+	// bound that the bounded observation cannot see). Each call to query(...).fetch() captures its clauses.
+	let fetchRows: TAnyMessageModel[];
+	let fetchCalls: unknown[][];
+	// Count returned by the release path's fetchCount() (number of cached rows above the old bound).
+	let fetchCountValue: number;
 
 	const wrapper = ({ children }: { children: ReactNode }) => <Provider store={mockedStore}>{children}</Provider>;
 
@@ -75,6 +81,9 @@ describe('useMessages', () => {
 		emitVisibleRows = null;
 		queryCalls = [];
 		unsubscribeSpies = [];
+		fetchRows = [];
+		fetchCalls = [];
+		fetchCountValue = 0;
 		jest.clearAllMocks();
 		// Reset historyLoaders so prior test dispatches don't trip the in-flight guard
 		mockedStore
@@ -95,7 +104,14 @@ describe('useMessages', () => {
 							unsubscribeSpies.push(unsubscribe);
 							return { unsubscribe };
 						}
-					})
+					}),
+					// Targeted one-shot read for the rejoin raise (region above the current bound).
+					fetch: jest.fn(() => {
+						fetchCalls.push(args);
+						return Promise.resolve(fetchRows);
+					}),
+					// Count of cached rows above the old bound, read by the release path to size the Live Window.
+					fetchCount: jest.fn(() => Promise.resolve(fetchCountValue))
 				};
 			})
 		}));
@@ -520,4 +536,220 @@ describe('useMessages', () => {
 		});
 		expect(mockReadThreads).not.toHaveBeenCalled();
 	});
+
+	const findBoundClause = (clauses: unknown[]) =>
+		clauses.find(
+			(clause): clause is { type: 'where'; left: string; comparison: { operator: string; right: { value: number } } } =>
+				!!clause &&
+				typeof clause === 'object' &&
+				(clause as { type?: string }).type === 'where' &&
+				(clause as { left?: string }).left === 'ts' &&
+				(clause as { comparison?: { operator?: string } }).comparison?.operator === 'lte'
+		);
+
+	it('does not apply an upper-bound ts clause when highTs is null (default Live Window)', async () => {
+		emittedRows = [msg({ id: 'm1' })];
+		renderUseMessages();
+		await waitFor(() => {
+			expect(queryCalls.length).toBeGreaterThan(0);
+		});
+		expect(findBoundClause(queryCalls[queryCalls.length - 1])).toBeUndefined();
+	});
+
+	it('applies the upper-bound ts clause only after an anchor is set, with take still last', async () => {
+		emittedRows = [msg({ id: 'm1' })];
+		const { result } = renderUseMessages();
+		await waitFor(() => {
+			expect(queryCalls.length).toBeGreaterThan(0);
+		});
+
+		// Default Live Window: no bound clause.
+		expect(findBoundClause(queryCalls[queryCalls.length - 1])).toBeUndefined();
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+
+		await waitFor(() => {
+			const lastCall = queryCalls[queryCalls.length - 1];
+			expect(findBoundClause(lastCall)).toBeDefined();
+		});
+
+		const lastCall = queryCalls[queryCalls.length - 1];
+		const bound = findBoundClause(lastCall);
+		expect(bound?.comparison.right.value).toBe(1500);
+		// take must remain the last clause so the existing pagination test stays valid.
+		expect(lastCall.at(-1)).toEqual(expect.objectContaining({ type: 'take' }));
+	});
+
+	it('seeds the window to a single page (QUERY_SIZE) when an anchor is set rather than growing', async () => {
+		emittedRows = [msg({ id: 'm1' })];
+		const { result } = renderUseMessages();
+		await waitFor(() => {
+			expect(queryCalls.length).toBeGreaterThan(0);
+		});
+
+		// Grow the Live Window a couple of pages first.
+		await act(async () => {
+			await result.current[2]();
+		});
+		await act(async () => {
+			await result.current[2]();
+		});
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+
+		await waitFor(() => {
+			expect(findBoundClause(queryCalls[queryCalls.length - 1])).toBeDefined();
+		});
+
+		const take = queryCalls[queryCalls.length - 1].find(
+			(clause): clause is { type: 'take'; count: number } =>
+				!!clause && typeof clause === 'object' && (clause as { type?: string }).type === 'take'
+		);
+		expect(take?.count).toBe(QUERY_SIZE);
+	});
+
+	it('exposes highTs and setHighTs as the 4th tuple element', async () => {
+		emittedRows = [msg({ id: 'm1' })];
+		const { result } = renderUseMessages();
+		await waitFor(() => {
+			expect(queryCalls.length).toBeGreaterThan(0);
+		});
+		expect(result.current[3].highTs).toBeNull();
+		expect(typeof result.current[3].setHighTs).toBe('function');
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+
+		await waitFor(() => {
+			expect(result.current[3].highTs).toBe(1500);
+		});
+	});
+
+	const findTakeClause = (clauses: unknown[]) =>
+		clauses.find(
+			(clause): clause is { type: 'take'; count: number } =>
+				!!clause && typeof clause === 'object' && (clause as { type?: string }).type === 'take'
+		);
+
+	// ms-since-epoch as the model's Date ts. Anchor bounds (highTs) are compared in ms, so a Date
+	// whose getTime() equals the chosen ms keeps `ts === highTs` boundary detection exact.
+	const at = (ms: number) => new Date(ms);
+	// Boundary Newer Loader of the Anchored Window: the row that sits exactly on the bound (ts === highTs).
+	const newerLoaderAt = (id: string, ms: number) => msg({ id, t: MessageTypeLoad.NEXT_CHUNK, ts: at(ms) });
+
+	it('raises the bound and GROWS the window when the boundary Newer Loader is consumed and another remains above', async () => {
+		emittedRows = [msg({ id: 'm1', ts: at(1000) }), newerLoaderAt('loader-H', 1500)];
+		const { result } = renderUseMessages();
+
+		// Anchor the window at the boundary loader's ts.
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+		await waitFor(() => {
+			expect(findBoundClause(queryCalls[queryCalls.length - 1])?.comparison.right.value).toBe(1500);
+		});
+		const takeBeforeRaise = findTakeClause(queryCalls[queryCalls.length - 1])?.count;
+		expect(takeBeforeRaise).toBe(QUERY_SIZE);
+
+		// The targeted read above the bound reveals the next batch plus a NEW Newer Loader at ts 1900.
+		fetchRows = [msg({ id: 'm2', ts: at(1700) }), newerLoaderAt('loader-H2', 1900)];
+
+		// loadNextMessages REMOVED the boundary loader: re-emit WITHOUT it (still under the old bound).
+		emitRows([msg({ id: 'm1', ts: at(1000) })]);
+
+		// Rejoin RAISE: bound climbs to the surviving loader's ts (1900) AND the window grows by a page.
+		await waitFor(() => {
+			expect(result.current[3].highTs).toBe(1900);
+		});
+		const lastCall = queryCalls[queryCalls.length - 1];
+		expect(findBoundClause(lastCall)?.comparison.right.value).toBe(1900);
+		expect(findTakeClause(lastCall)?.count).toBe(QUERY_SIZE * 2);
+	});
+
+	it('releases the anchor to a Live Window when the boundary Newer Loader is consumed and the Gap has closed', async () => {
+		emittedRows = [msg({ id: 'm1', ts: at(1000) }), newerLoaderAt('loader-H', 1500)];
+		const { result } = renderUseMessages();
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+		await waitFor(() => {
+			expect(findBoundClause(queryCalls[queryCalls.length - 1])?.comparison.right.value).toBe(1500);
+		});
+
+		// The targeted read reveals the next batch but NO new Newer Loader: the Gap to the Live Tail closed.
+		fetchRows = [msg({ id: 'm2', ts: at(1700) }), msg({ id: 'm3', ts: at(1800) })];
+
+		// loadNextMessages consumed the boundary loader: re-emit WITHOUT it.
+		emitRows([msg({ id: 'm1', ts: at(1000) })]);
+
+		// Rejoin RELEASE: bound becomes null → Live Window. The captured query drops the Q.lte clause.
+		await waitFor(() => {
+			expect(result.current[3].highTs).toBeNull();
+		});
+		expect(findBoundClause(queryCalls[queryCalls.length - 1])).toBeUndefined();
+	});
+
+	it('grows the released Live Window to preserve the reading position instead of snapping to the Live Tail', async () => {
+		// Anchored deep below a large cached newer island. When the Gap closes and the window releases,
+		// take(count) must span from the Live Tail down past the original target — otherwise the target is
+		// evicted and the list snaps to the tail (NATIVE-1229 #3 reading-position loss).
+		emittedRows = [msg({ id: 'm1', ts: at(1000) }), newerLoaderAt('loader-H', 1500)];
+		const { result } = renderUseMessages();
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+		await waitFor(() => {
+			expect(findBoundClause(queryCalls[queryCalls.length - 1])?.comparison.right.value).toBe(1500);
+		});
+		const anchoredTake = findTakeClause(queryCalls[queryCalls.length - 1])?.count ?? 0;
+
+		// Gap closed (no Newer Loader above the bound), but 120 messages sit above it (the cached island).
+		fetchRows = [msg({ id: 'm2', ts: at(1700) }), msg({ id: 'm3', ts: at(1800) })];
+		fetchCountValue = 120;
+
+		// loadNextMessages consumed the boundary loader: re-emit without it.
+		emitRows([msg({ id: 'm1', ts: at(1000) })]);
+
+		await waitFor(() => {
+			expect(result.current[3].highTs).toBeNull();
+		});
+
+		// The released Live Window's take spans the anchored window PLUS the 120 messages above it, so the
+		// deep target survives the release rather than falling outside take(count).
+		const releasedTake = findTakeClause(queryCalls[queryCalls.length - 1])?.count ?? 0;
+		expect(releasedTake).toBeGreaterThanOrEqual(anchoredTake + 120);
+	});
+
+	it('never releases across an open Gap: keeps highTs finite while a Newer Loader survives above the bound', async () => {
+		emittedRows = [msg({ id: 'm1', ts: at(1000) }), newerLoaderAt('loader-H', 1500)];
+		const { result } = renderUseMessages();
+
+		act(() => {
+			result.current[3].setHighTs(1500);
+		});
+		await waitFor(() => {
+			expect(findBoundClause(queryCalls[queryCalls.length - 1])?.comparison.right.value).toBe(1500);
+		});
+
+		// The targeted read still shows a Newer Loader above the bound — the Gap is NOT closed.
+		fetchRows = [msg({ id: 'm2', ts: at(1700) }), newerLoaderAt('loader-H2', 1900)];
+
+		// Consume the boundary loader.
+		emitRows([msg({ id: 'm1', ts: at(1000) })]);
+
+		// The Gap is still open, so the window must NOT release to a Live Window: highTs stays finite
+		// (it climbs to the surviving loader instead of becoming null), and the upper bound persists.
+		await waitFor(() => {
+			expect(result.current[3].highTs).toBe(1900);
+		});
+		expect(result.current[3].highTs).not.toBeNull();
+		expect(findBoundClause(queryCalls[queryCalls.length - 1])).toBeDefined();
+	});
 });