fix: keep MessageList scrolled to the bottom (#3068)

Author: MartinCupela

src/components/Attachment/Giphy.tsx

@@ -8,33 +8,60 @@ import {
   useTranslationContext,
 } from '../../context';
 import { IconGiphy } from '../Icons';
-import { useMemo } from 'react';
+import { type CSSProperties, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { ImageAttachmentConfiguration } from '../../types/types';
 
 export type GiphyAttachmentProps = {
   attachment: Attachment;
 };
 
 export const Giphy = ({ attachment }: GiphyAttachmentProps) => {
-  const { giphyVersion: giphyVersionName } = useChannelStateContext();
+  const { giphyVersion: giphyVersionName, imageAttachmentSizeHandler } =
+    useChannelStateContext();
   const { BaseImage = DefaultBaseImage } = useComponentContext();
   const { t } = useTranslationContext();
   const usesDefaultBaseImage = BaseImage === DefaultBaseImage;
+  const imageElement = useRef<HTMLImageElement>(null);
+  const [attachmentConfiguration, setAttachmentConfiguration] = useState<
+    ImageAttachmentConfiguration | undefined
+  >(undefined);
 
   const imageDescriptors = useMemo(
     () => toGalleryItemDescriptors(attachment, { giphyVersionName }),
     [attachment, giphyVersionName],
   );
+  const alt = imageDescriptors && imageDescriptors.alt;
+  const dimensions = imageDescriptors && imageDescriptors.dimensions;
+  const imageUrl = imageDescriptors && imageDescriptors.imageUrl;
+  const title = imageDescriptors && imageDescriptors.title;
+  const resolvedImageUrl = attachmentConfiguration?.url || imageUrl;
+  const imageStyleVariables = useMemo(() => {
+    const originalHeight = Number(dimensions?.height);
+    const originalWidth = Number(dimensions?.width);
 
-  if (!imageDescriptors?.imageUrl) return null;
+    return {
+      '--original-height': String(originalHeight > 1 ? originalHeight : 1000000),
+      '--original-width': String(originalWidth > 1 ? originalWidth : 1000000),
+    } as CSSProperties;
+  }, [dimensions?.height, dimensions?.width]);
 
-  const { alt, dimensions, imageUrl, title } = imageDescriptors;
+  useLayoutEffect(() => {
+    if (!imageElement.current || !imageAttachmentSizeHandler) return;
+
+    const config = imageAttachmentSizeHandler(attachment, imageElement.current);
+    setAttachmentConfiguration(config);
+  }, [attachment, imageAttachmentSizeHandler]);
+
+  if (!imageUrl) return null;
 
   return (
     <div className={clsx(`str-chat__message-attachment-giphy`)}>
       <BaseImage
         alt={alt ?? title ?? t('User uploaded content')}
         height={dimensions?.height}
-        src={imageUrl}
+        ref={imageElement}
+        src={resolvedImageUrl}
+        style={imageStyleVariables}
         width={dimensions?.width}
         {...(usesDefaultBaseImage ? { showDownloadButtonOnError: false } : {})}
       />

src/components/Attachment/__tests__/Attachment.test.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import { render, screen, waitFor } from '@testing-library/react';
 import { nanoid } from 'nanoid';
+import { vi } from 'vitest';
 
 import {
   generateAttachmentAction,
@@ -18,10 +19,8 @@ import {
 
 import { Attachment } from '../Attachment';
 import { SUPPORTED_VIDEO_FORMATS } from '../utils';
-import {
-  generateScrapedVideoAttachment,
-  mockChannelStateContext,
-} from '../../../mock-builders';
+import { generateScrapedVideoAttachment } from '../../../mock-builders';
+import type { ChannelStateContextValue } from '../../../context';
 import { ChannelStateProvider } from '../../../context';
 
 const UNSUPPORTED_ATTACHMENT_TEST_ID = 'attachment-unsupported';
@@ -58,16 +57,20 @@ const ATTACHMENTS = {
   },
 };
 
-const renderComponent = (props) =>
+const renderComponent = (
+  props,
+  channelStateValue = {},
+  { useDefaultGiphy = false } = {},
+) =>
   render(
-    <ChannelStateProvider value={mockChannelStateContext()}>
+    <ChannelStateProvider value={channelStateValue as ChannelStateContextValue}>
       <Attachment
         AttachmentActions={AttachmentActions}
         Audio={Audio}
         Card={Card}
         File={File}
         Geolocation={Geolocation}
-        Giphy={Giphy}
+        {...(!useDefaultGiphy ? { Giphy } : {})}
         Image={Image}
         Media={Media}
         ModalGallery={ModalGallery}
@@ -184,6 +187,25 @@ describe('attachment', () => {
         expect(screen.getByTestId('giphy-attachment')).toBeInTheDocument();
       });
     });
+
+    it('should apply imageAttachmentSizeHandler to giphy attachments', async () => {
+      const resizedGiphyUrl = 'https://example.com/resized.gif';
+      const imageAttachmentSizeHandler = vi.fn(() => ({ url: resizedGiphyUrl }));
+
+      renderComponent(
+        { attachments: [ATTACHMENTS.scraped.giphy] },
+        { giphyVersion: 'fixed_height', imageAttachmentSizeHandler },
+        { useDefaultGiphy: true },
+      );
+
+      await waitFor(() => {
+        expect(imageAttachmentSizeHandler).toHaveBeenCalled();
+        const imageElement = screen.getByTestId('str-chat__base-image');
+        expect(imageElement.getAttribute('src')).toBe(resizedGiphyUrl);
+        expect(imageElement.style.getPropertyValue('--original-height')).toBe('200');
+        expect(imageElement.style.getPropertyValue('--original-width')).toBe('200');
+      });
+    });
   });
 
   describe('combines scraped & uploaded content', () => {

src/components/BaseImage/toBaseImageDescriptors.ts

@@ -34,7 +34,7 @@ export type BaseImageDescriptor = {
 export const toBaseImageDescriptors = (
   attachment: AttachmentPreviewableInGallery,
   options: { giphyVersionName?: string } = {},
-): BaseImageDescriptor | void => {
+): BaseImageDescriptor | undefined => {
   if (isGiphyAttachment(attachment)) {
     const giphyVersion =
       options?.giphyVersionName && attachment.giphy
@@ -98,4 +98,6 @@ export const toBaseImageDescriptors = (
       title: attachment.title,
     };
   }
+
+  return undefined;
 };

src/components/Gallery/GalleryContext.tsx

@@ -17,10 +17,12 @@ export type GalleryItem = Omit<BaseImageProps, 'src'> & {
  */
 export const toGalleryItemDescriptors = (
   ...args: Parameters<typeof toBaseImageDescriptors>
-): Pick<
-  GalleryItem,
-  'alt' | 'dimensions' | 'imageUrl' | 'title' | 'videoThumbnailUrl' | 'videoUrl'
-> | void => toBaseImageDescriptors(...args);
+):
+  | Pick<
+      GalleryItem,
+      'alt' | 'dimensions' | 'imageUrl' | 'title' | 'videoThumbnailUrl' | 'videoUrl'
+    >
+  | undefined => toBaseImageDescriptors(...args);
 
 export type GalleryContextValue = {
   /** Whether clicking the empty gallery background should request close */

src/components/MessageList/hooks/MessageList/useScrollLocationLogic.tsx

@@ -5,17 +5,35 @@ import { useMessageListScrollManager } from './useMessageListScrollManager';
 import type { LocalMessage } from 'stream-chat';
 
 export type UseScrollLocationLogicParams = {
+  /** Disables automatic scroll-to-bottom updates after message changes. */
   disableAutoScrollToBottom?: boolean;
+  /** Disables scroll-management adjustments (anchor restore, append/prepend handling). */
   disableScrollManagement?: boolean;
+  /** True when there are newer messages to load beyond the currently rendered page. */
   hasMoreNewer: boolean;
+  /** Scrollable message-list container element. */
   listElement: HTMLDivElement | null;
+  /** Threshold used to detect older-page pagination proximity near the top. */
   loadMoreScrollThreshold: number;
+  /** Indicates whether older-page pagination is currently in progress. */
   loadingMore?: boolean;
+  /** Hard-disable all autoscroll behavior. */
   suppressAutoscroll: boolean;
+  /** Current rendered message set used for scroll reconciliation. */
   messages?: LocalMessage[];
+  /** Distance from bottom (px) considered as "near bottom". */
   scrolledUpThreshold?: number;
 };
 
+/**
+ * Centralized scroll-position logic for MessageList.
+ *
+ * Responsibilities:
+ * - Keep viewport stable during prepend/append pagination updates.
+ * - Track whether the list is near bottom and expose that state to UI.
+ * - Auto-scroll to bottom when appropriate while respecting suppression flags.
+ * - Perform a short hydration settle pass so freshly loaded lists land at bottom.
+ */
 export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) => {
   const {
     disableAutoScrollToBottom = false,
@@ -41,6 +59,7 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
   const closeToBottom = useRef(false);
   const closeToTop = useRef(false);
   const previousScrollTopRef = useRef(0);
+  const previousMessagesLengthRef = useRef(messages.length);
   const anchorRestoreCleanupRef = useRef<(() => void) | null>(null);
 
   const captureAnchor = useCallback(() => {
@@ -225,6 +244,10 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
     [hasMoreNewer, justReachedLatestMessageSet, listElement, suppressAutoscroll],
   );
 
+  /**
+   * Keeps wrapper geometry up to date and handles the "reached latest merged set"
+   * path where existing viewport position must be preserved.
+   */
   useLayoutEffect(() => {
     if (listElement) {
       setWrapperRect(listElement.getBoundingClientRect());
@@ -247,6 +270,85 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [disableAutoScrollToBottom, justReachedLatestMessageSet, listElement, hasMoreNewer]);
 
+  /**
+   * Short post-render bottom settle. This is intentionally small (immediate + 2 retries)
+   * to catch late layout updates without keeping the list in a prolonged lock loop.
+   */
+  useLayoutEffect(() => {
+    if (
+      !listElement ||
+      disableAutoScrollToBottom ||
+      hasMoreNewer ||
+      suppressAutoscroll ||
+      justReachedLatestMessageSet ||
+      isRestoringOlderAnchorRef.current
+    ) {
+      return;
+    }
+
+    const initialDistanceToBottom =
+      listElement.scrollHeight - (listElement.scrollTop + listElement.clientHeight);
+    const messagesHydrated =
+      previousMessagesLengthRef.current === 0 && messages.length > 0;
+
+    if (initialDistanceToBottom > scrolledUpThreshold && !messagesHydrated) {
+      return;
+    }
+
+    let keepPinnedToBottom = true;
+
+    const maybeScrollToBottom = () => {
+      if (keepPinnedToBottom) {
+        scrollToBottom();
+      }
+    };
+
+    maybeScrollToBottom();
+    const settleDelays = [80, messagesHydrated ? 260 : 420, 900, 1700];
+    const settleTimeoutIds = settleDelays.map((delay) =>
+      setTimeout(maybeScrollToBottom, delay),
+    );
+
+    const stopKeepingPinnedToBottom = () => {
+      keepPinnedToBottom = false;
+    };
+
+    // Any direct user interaction with the scroller disables the temporary
+    // initial-load pin, so manual scrolling is never force-overridden.
+    listElement.addEventListener('pointerdown', stopKeepingPinnedToBottom, {
+      passive: true,
+    });
+    listElement.addEventListener('touchstart', stopKeepingPinnedToBottom, {
+      passive: true,
+    });
+    listElement.addEventListener('wheel', stopKeepingPinnedToBottom, {
+      passive: true,
+    });
+    listElement.addEventListener('keydown', stopKeepingPinnedToBottom);
+
+    const pinWindowTimeoutId = setTimeout(() => {
+      stopKeepingPinnedToBottom();
+    }, 2200);
+
+    return () => {
+      settleTimeoutIds.forEach(clearTimeout);
+      clearTimeout(pinWindowTimeoutId);
+      listElement.removeEventListener('pointerdown', stopKeepingPinnedToBottom);
+      listElement.removeEventListener('touchstart', stopKeepingPinnedToBottom);
+      listElement.removeEventListener('wheel', stopKeepingPinnedToBottom);
+      listElement.removeEventListener('keydown', stopKeepingPinnedToBottom);
+    };
+  }, [
+    disableAutoScrollToBottom,
+    hasMoreNewer,
+    justReachedLatestMessageSet,
+    listElement,
+    messages.length,
+    scrollToBottom,
+    scrolledUpThreshold,
+    suppressAutoscroll,
+  ]);
+
   const updateScrollTop = useMessageListScrollManager({
     captureAnchor,
     disableScrollManagement: disableScrollManagement || isRestoringOlderAnchorRef.current,
@@ -276,6 +378,14 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
     previousHasMoreNewerRef.current = hasMoreNewer;
   }, [hasMoreNewer]);
 
+  useLayoutEffect(() => {
+    previousMessagesLengthRef.current = messages.length;
+  }, [messages.length]);
+
+  /**
+   * Updates cached scroll metrics and bottom/top proximity state used by
+   * notifications, autoscroll decisions, and paginator behavior.
+   */
   const onScroll = useCallback(
     (event: React.UIEvent<HTMLDivElement>) => {
       const element = event.target as HTMLDivElement;
@@ -286,10 +396,13 @@ export const useScrollLocationLogic = (params: UseScrollLocationLogicParams) =>
 
       const offsetHeight = element.offsetHeight;
       const scrollHeight = element.scrollHeight;
+      const distanceToBottom = scrollHeight - (scrollTop + offsetHeight);
+      const bottomEnterThreshold = Math.max(Math.floor(scrolledUpThreshold * 0.6), 24);
 
       const prevCloseToBottom = closeToBottom.current;
-      closeToBottom.current =
-        scrollHeight - (scrollTop + offsetHeight) < scrolledUpThreshold;
+      closeToBottom.current = prevCloseToBottom
+        ? distanceToBottom < scrolledUpThreshold
+        : distanceToBottom < bottomEnterThreshold;
       closeToTop.current = scrollTop < scrolledUpThreshold;
 
       if (closeToBottom.current) {