Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(dashboard): scroll to a live message after its row renders

Yudhi Armyndharis6c2acf891eba
diff --git a/dashboard/src/hooks/useChatScrollPosition.render.test.ts b/dashboard/src/hooks/useChatScrollPosition.render.test.ts
index 4ee1fa12c..9865ce0ce 100644
--- a/dashboard/src/hooks/useChatScrollPosition.render.test.ts
+++ b/dashboard/src/hooks/useChatScrollPosition.render.test.ts
@@ -254,8 +254,8 @@ const hookRef: MutableRefObject<ReturnType<typeof useChatScrollPosition> | null>
const hook = (): ReturnType<typeof useChatScrollPosition> =>
hookRef.current as ReturnType<typeof useChatScrollPosition>;
-function Probe({ chatId }: { chatId: string | null }) {
- const result = useChatScrollPosition(chatId, chatId !== null, false);
+function Probe({ chatId, loaded = chatId !== null }: { chatId: string | null; loaded?: boolean }) {
+ const result = useChatScrollPosition(chatId, loaded, false);
useEffect(() => {
hookRef.current = result;
});
@@ -472,3 +472,139 @@ test('a reader scrolling back to where a pin left the thread is still the reader
restore();
}
});
+
+// ── Following a live message ─────────────────────────────────────────────────
+// The Chats page announces a message when it writes it to the cache, and the row reaches the DOM after the cache
+// notifies its observers and React renders, which a frame can overtake.
+
+test('a live message is followed by the commit that adds its row, even when a frame ran first', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+
+ hook().onMessageAppended('incoming');
+ await nextFrame(); // a frame lands before the commit: the thread has not grown yet
+ rerender(createElement(Probe, { chatId: 'A' })); // so does a commit of something else, the sidebar
+ g.height += 300;
+ rerender(createElement(Probe, { chatId: 'A' })); // the row
+ await nextFrame();
+ assert.equal(el.scrollTop, g.height - CLIENT_HEIGHT, 'the newest message was left below the fold');
+ } finally {
+ restore();
+ }
+});
+
+test('a reader who scrolled away before the row was committed is not pulled back down', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+
+ hook().onMessageAppended('incoming');
+ readerScrollsTo(el, 3000);
+ await nextFrame();
+ g.height += 300;
+ rerender(createElement(Probe, { chatId: 'A' }));
+ await nextFrame();
+ assert.equal(el.scrollTop, 3000, 'the reader was taken to the bottom');
+ } finally {
+ restore();
+ }
+});
+
+test('a message announced in a chat that was left before its row committed pins nothing in the next chat', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+ rerender(createElement(Probe, { chatId: 'B' }));
+ fireEvent.scroll(el);
+ readerScrollsTo(el, 4140); // the spot the reader left in B, just above its bottom
+ rerender(createElement(Probe, { chatId: 'A' }));
+ fireEvent.scroll(el);
+
+ hook().onMessageAppended('incoming');
+ rerender(createElement(Probe, { chatId: 'B' })); // the reader goes back to B before the row lands
+ fireEvent.scroll(el);
+ g.height += 300; // B's thread grows for a reason of its own
+ rerender(createElement(Probe, { chatId: 'B' }));
+ await nextFrame();
+ assert.equal(el.scrollTop, 4140, "the other chat's message moved the reader's spot in B");
+ } finally {
+ restore();
+ }
+});
+
+test('a message the reader is far from the bottom of leaves their position alone', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+ readerScrollsTo(el, 1000);
+
+ await liveMessage(g, rerender, 'incoming', 300);
+ assert.equal(el.scrollTop, 1000);
+ } finally {
+ restore();
+ }
+});
+
+test('a message the reader sent always scrolls the thread to it', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+ readerScrollsTo(el, 1000);
+
+ await liveMessage(g, rerender, 'outgoing', 300);
+ assert.equal(el.scrollTop, g.height - CLIENT_HEIGHT);
+ } finally {
+ restore();
+ }
+});
+
+test('a message announced while its chat is still loading does not override where the chat opens', async () => {
+ const { render, screen, fireEvent, cleanup } = rtl;
+ cleanup();
+ const g: Geometry = { height: 4600, top: 0 };
+ const restore = installGeometry(g);
+ try {
+ const { rerender } = render(createElement(Probe, { chatId: 'A' }));
+ const el = screen.getByTestId('thread');
+ fireEvent.scroll(el);
+ readerScrollsTo(el, 3000); // the spot the reader left in A
+ rerender(createElement(Probe, { chatId: null }));
+
+ // A is opened again from a cold cache: a spinner, then the thread. The message arrives in between.
+ g.height = CLIENT_HEIGHT;
+ rerender(createElement(Probe, { chatId: 'A', loaded: false }));
+ hook().onMessageAppended('incoming');
+ g.height = 4900;
+ rerender(createElement(Probe, { chatId: 'A', loaded: true }));
+ await nextFrame();
+ assert.equal(el.scrollTop, 3000, 'the message took the reader from the spot they left');
+ } finally {
+ restore();
+ }
+});
diff --git a/dashboard/src/hooks/useChatScrollPosition.ts b/dashboard/src/hooks/useChatScrollPosition.ts
index b3a80c344..969946b01 100644
--- a/dashboard/src/hooks/useChatScrollPosition.ts
+++ b/dashboard/src/hooks/useChatScrollPosition.ts
@@ -1,5 +1,5 @@
import { useCallback, useEffect, useLayoutEffect, useRef, type RefObject } from 'react';
-import { decideScroll, type ScrollDirection } from '../utils/scrollDecision.ts';
+import { decideScroll, type ScrollDirection, type ScrollGeometry } from '../utils/scrollDecision.ts';
/**
* Decide the restore target on a chat switch or load-resolve.
@@ -47,8 +47,10 @@ export function decideRestoreTarget(
* (spinner first, then data) correctly waits to restore until the messages
* list is mounted with non-zero scrollHeight.
* - On message append: `onMessageAppended(direction)` snapshots the geometry
- * BEFORE the new message is committed, then defers the scroll-to-bottom (if
- * any) to the next frame so the new message is already in the DOM.
+ * BEFORE the new message is committed and decides whether the thread follows
+ * it; the scroll-to-bottom (if any) is applied by the commit that grows the
+ * thread, so the new message is already in the DOM. A frame is not that
+ * commit: it can run between the cache write and the render.
* - Pinned-to-bottom: media (`<img>`/`<video>`) has no intrinsic size before it
* decodes, so the container's scrollHeight GROWS after the initial restore —
* silently un-bottoming the view (the thread looks like it "opened at the
@@ -173,6 +175,11 @@ export function useChatScrollPosition(
// before a write that then moved nothing. A browser raises one event per frame however many writes the
// frame held, so a flag cleared by a write that moved nothing handed the frame's one event to the reader.
const programmaticTopRef = useRef<number | null>(null);
+ // A live message the thread is to follow, until the commit that adds its row applies it (see the layout effect
+ // after the older-page landing).
+ const pendingFollowRef = useRef<{ chat: string | null; direction: ScrollDirection; geometry: ScrollGeometry } | null>(
+ null,
+ );
// See the layout effect below.
const prevScrollHeightRef = useRef<number>(0);
const awaitingOlderPageRef = useRef<boolean>(false);
@@ -309,6 +316,23 @@ export function useChatScrollPosition(
}
});
+ // Applies a live message's follow on the first commit that grows the thread (see onMessageAppended): the row
+ // is in the DOM, and no frame can have run between the commit and the pin. The reader may have scrolled away
+ // while the row was on its way, so the follow question is asked again, against where they are now.
+ useLayoutEffect(() => {
+ const follow = pendingFollowRef.current;
+ const el = containerRef.current;
+ if (!follow || !el) return;
+ // The chat the message was announced in is not the one on screen any more.
+ if (follow.chat !== prevChatIdRef.current) {
+ pendingFollowRef.current = null;
+ return;
+ }
+ if (el.scrollHeight <= follow.geometry.scrollHeight) return;
+ pendingFollowRef.current = null;
+ if (decideScroll(follow.direction, { ...follow.geometry, scrollTop: el.scrollTop }) === 'bottom') followBottom(el);
+ });
+
const onOlderMessagesRequested = useCallback(() => {
const el = containerRef.current;
if (!el) return;
@@ -317,23 +341,14 @@ export function useChatScrollPosition(
awaitingOlderPageRef.current = true;
}, []);
- const onMessageAppended = useCallback(
- (direction: ScrollDirection) => {
- const el = containerRef.current;
- if (!el) return;
- const action = decideScroll(direction, {
- scrollTop: el.scrollTop,
- scrollHeight: el.scrollHeight,
- clientHeight: el.clientHeight,
- });
- if (action === 'preserve') return;
- requestAnimationFrame(() => {
- const cur = containerRef.current;
- if (cur) followBottom(cur);
- });
- },
- [followBottom],
- );
+ const onMessageAppended = useCallback((direction: ScrollDirection) => {
+ const el = containerRef.current;
+ // A chat that has not rendered its thread has nothing to follow: the restore decides where it opens.
+ if (!el || !loadedRef.current) return;
+ const geometry = { scrollTop: el.scrollTop, scrollHeight: el.scrollHeight, clientHeight: el.clientHeight };
+ if (decideScroll(direction, geometry) === 'preserve') return;
+ pendingFollowRef.current = { chat: prevChatIdRef.current, direction, geometry };
+ }, []);
// Media has no layout box before it decodes. While pinned, each decode re-pins to the bottom;
// while a 'saved' restore is pending, each decode RE-APPLIES the saved scrollTop (the first write