fix: flash list scroll to behaviour (#3602)

## 🎯 Goal

This PR addresses 2 issues with `MessageFlashList` which have made
`scrollTo` behaviour unreliable.

1. It should fix (or at least make a lot better) the issue of being
snapped back to the end of the list whenever we try to scroll to a
quoted message for the very first time
2. It should address not being able to scroll to the first unread
message

Even though these 2 issues are seemingly similar, their underlying
causes are completely different.

#### Quoted message scroll to

This particular issue happens specifically when we've loaded the
messages into memory that we want to scroll to (so loading a completely
different `messageSet` is working fine). The offender here is MVCP and
scrolling to bottom in particular. I'm pretty certain that there's an
upstream bug here, however I did not have a chance to debug it more
thoroughly and find the actual root cause. Roughly what goes on is the
following:

- The list mounts, MVCP gets armed
- We press on a quoted message and begin scrolling to it
- Mid scroll, MVCP decides something's changed (because of the fact that
recycling kicks in and layout gets revalidated) and triggers a pending
scroll
- The scroll is immediately consumed, snapping us back just after the
quoted message scroll finishes

I actually had a patch in `FlashList` which allows us to clear all
pending MVCP scrolls and also suspend MVCP from doing anything and it
worked like a charm (like an imperative API).

However for now, this will have to do. At the very least, even when the
issue happens it should reconcile shortly after and fix its positioning.

#### Initial scroll to first unread

This issue on the other hand is completely unrelated to MVCP. It's
actually related to our automatic scrolling mechanism, which happens on
mount and then also whenever `autoscrollToRecent` actually changes.
Namely, if we look into `FlashList`'s implementation we can see that
`scrollToEnd` is actually ultimately wrapped within a `setTimeout`,
likely to try to delay it natively on the JS runtime for timing
purposes. However, this also means that if a state update happens really
quickly (for example `targetedMessage` updating) we'll end up making the
2 scrolls race. `scrollToEnd` typically wins because it's invoked later
and also because it invokes the underlying scroll view's ref rather than
some abstraction.

We need this custom handling because `initialScrollIndex` for
`FlashList` is very often not correct at all (and off by some number of
offset). This is especially true whenever we scroll between 2 message
sets and virtually load new data. I've yet to find why this is but maybe
some day.

To prevent this, we expose a new API on the `Channel` level that allows
us to anticipate when we're about to scroll to a targeted message,
bypassing the `scrollToEnd` entirely in favor of having a pending
scroll.

These fixes will be ported back to V8 as well.

## 🛠 Implementation details

<!-- Provide a description of the implementation -->

## 🎨 UI Changes

<!-- Add relevant screenshots -->

<details>
<summary>iOS</summary>


<table>
    <thead>
        <tr>
            <td>Before</td>
            <td>After</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>
                <!--<img src="" /> -->
            </td>
            <td>
                <!--<img src="" /> -->
            </td>
        </tr>
    </tbody>
</table>
</details>


<details>
<summary>Android</summary>

<table>
    <thead>
        <tr>
            <td>Before</td>
            <td>After</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>
                <!--<img src="" /> -->
            </td>
            <td>
                <!--<img src="" /> -->
            </td>
        </tr>
    </tbody>
</table>
</details>

## 🧪 Testing

<!-- Explain how this change can be tested (or why it can't be tested)
-->

## ☑️ Checklist

- [ ] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required)
- [ ] PR targets the `develop` branch
- [ ] Documentation is updated
- [ ] New code is tested in main example apps, including all possible
scenarios
  - [ ] SampleApp iOS and Android
  - [ ] Expo iOS and Android

Author: isekovanic

package/src/components/Channel/Channel.tsx

@@ -567,6 +567,18 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
     channel,
   });
 
+  const shouldLoadInitialChannelAtFirstUnreadMessage = useStableCallback((unreadCount?: number) => {
+    if (messageId || !initialScrollToFirstUnreadMessage || !client.user) {
+      return false;
+    }
+
+    return (unreadCount ?? channel.countUnread()) > scrollToFirstUnreadThreshold;
+  });
+
+  const hasPendingInitialTargetLoad = useStableCallback(() => {
+    return !!messageId || shouldLoadInitialChannelAtFirstUnreadMessage();
+  });
+
   const { setMessages: copyMessagesStateFromChannel, viewabilityChangedCallback } =
     usePrunableMessageList({ maximumMessageLimit, setMessages: rawCopyMessagesStateFromChannel });
 
@@ -693,6 +705,7 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
     const initChannel = async () => {
       setLastRead(new Date());
       const unreadCount = channel.countUnread();
+      const shouldLoadAtFirstUnread = shouldLoadInitialChannelAtFirstUnreadMessage(unreadCount);
       if (!channel || !shouldSyncChannel) {
         return;
       }
@@ -722,13 +735,14 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
 
       if (messageId) {
         await loadChannelAroundMessage({ messageId, setTargetedMessage });
-      } else if (
-        initialScrollToFirstUnreadMessage &&
-        client.user &&
-        unreadCount > scrollToFirstUnreadThreshold
-      ) {
+      } else if (shouldLoadAtFirstUnread) {
+        const clientUserId = client.user?.id;
+        if (!clientUserId) {
+          return;
+        }
+
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { user, ...ownReadState } = channel.state.read[client.user.id];
+        const { user, ...ownReadState } = channel.state.read[clientUserId];
 
         await loadChannelAtFirstUnreadMessage({
           channelUnreadState: ownReadState,
@@ -1578,6 +1592,7 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
     setChannelUnreadState,
     setLastRead,
     setTargetedMessage,
+    hasPendingInitialTargetLoad,
     targetedMessage,
     threadList,
     uploadAbortControllerRef,

package/src/components/Channel/hooks/useCreateChannelContext.ts

@@ -27,6 +27,7 @@ export const useCreateChannelContext = ({
   setChannelUnreadState,
   setLastRead,
   setTargetedMessage,
+  hasPendingInitialTargetLoad,
   targetedMessage,
   threadList,
   uploadAbortControllerRef,
@@ -69,6 +70,7 @@ export const useCreateChannelContext = ({
       setChannelUnreadState,
       setLastRead,
       setTargetedMessage,
+      hasPendingInitialTargetLoad,
       targetedMessage,
       threadList,
       uploadAbortControllerRef,

package/src/components/MessageList/MessageFlashList.tsx

@@ -132,6 +132,7 @@ type MessageFlashListPropsWithContext = Pick<
     | 'scrollToFirstUnreadThreshold'
     | 'setChannelUnreadState'
     | 'setTargetedMessage'
+    | 'hasPendingInitialTargetLoad'
     | 'targetedMessage'
     | 'threadList'
     | 'maximumMessageLimit'
@@ -289,6 +290,7 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
     setChannelUnreadState,
     setFlatListRef,
     setTargetedMessage,
+    hasPendingInitialTargetLoad,
     targetedMessage,
     thread,
     threadInstance,
@@ -388,11 +390,15 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
 
   useEffect(() => {
     if (autoscrollToRecent && flashListRef.current) {
+      if (hasPendingInitialTargetLoad?.()) {
+        return;
+      }
+
       flashListRef.current.scrollToEnd({
         animated: true,
       });
     }
-  }, [autoscrollToRecent]);
+  }, [autoscrollToRecent, hasPendingInitialTargetLoad]);
 
   const maintainVisibleContentPosition = useMemo(() => {
     return {
@@ -408,18 +414,6 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
     }
   }, [disabled]);
 
-  const indexToScrollToRef = useRef<number | undefined>(undefined);
-
-  const initialIndexToScrollTo = useMemo(() => {
-    return targetedMessage
-      ? processedMessageList.findIndex((message) => message?.id === targetedMessage)
-      : -1;
-  }, [processedMessageList, targetedMessage]);
-
-  useEffect(() => {
-    indexToScrollToRef.current = initialIndexToScrollTo;
-  }, [initialIndexToScrollTo]);
-
   /**
    * Check if a messageId needs to be scrolled to after list loads, and scroll to it
    * Note: This effect fires on every list change with a small debounce so that scrolling isnt abrupted by an immediate rerender
@@ -440,13 +434,29 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
       scrollToDebounceTimeoutRef.current = setTimeout(() => {
         clearTimeout(scrollToDebounceTimeoutRef.current);
 
-        // now scroll to it
-        flashListRef.current?.scrollToIndex({
-          animated: true,
-          index: indexOfParentInMessageList,
-          viewPosition: 0.5,
+        const scrollToIndex = async () => {
+          const list = flashListRef.current;
+
+          if (!list) {
+            return false;
+          }
+
+          await list.scrollToIndex({
+            index: indexOfParentInMessageList,
+            animated: true,
+            viewPosition: 0.5,
+          });
+
+          return true;
+        };
+
+        requestAnimationFrame(async () => {
+          await scrollToIndex();
+          requestAnimationFrame(async () => {
+            await scrollToIndex();
+            setTargetedMessage(undefined);
+          });
         });
-        setTargetedMessage(undefined);
       }, WAIT_FOR_SCROLL_TIMEOUT);
     }
   }, [loadChannelAroundMessage, processedMessageList, setTargetedMessage, targetedMessage]);
@@ -456,8 +466,6 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
       (message) => message?.id === messageId,
     );
 
-    indexToScrollToRef.current = indexOfParentInMessageList;
-
     try {
       if (indexOfParentInMessageList === -1) {
         clearTimeout(scrollToDebounceTimeoutRef.current);
@@ -529,7 +537,6 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
       setScrollToBottomButtonVisible(true);
       return;
     } else {
-      indexToScrollToRef.current = undefined;
       setAutoscrollToRecent(true);
     }
     const latestNonCurrentMessageBeforeUpdate = latestNonCurrentMessageBeforeUpdateRef.current;
@@ -1064,9 +1071,6 @@ const MessageFlashListWithContext = (props: MessageFlashListPropsWithContext) =>
             data={processedMessageList}
             drawDistance={800}
             getItemType={getItemTypeInternal}
-            initialScrollIndex={
-              indexToScrollToRef.current === -1 ? undefined : indexToScrollToRef.current
-            }
             keyboardShouldPersistTaps='handled'
             keyExtractor={keyExtractor}
             ListFooterComponent={ListFooterComponent}
@@ -1203,6 +1207,7 @@ export const MessageFlashList = (props: MessageFlashListProps) => {
     scrollToFirstUnreadThreshold,
     setChannelUnreadState,
     setTargetedMessage,
+    hasPendingInitialTargetLoad,
     targetedMessage,
     threadList,
   } = useChannelContext();
@@ -1246,6 +1251,7 @@ export const MessageFlashList = (props: MessageFlashListProps) => {
         scrollToFirstUnreadThreshold,
         setChannelUnreadState,
         setTargetedMessage,
+        hasPendingInitialTargetLoad,
         shouldShowUnreadUnderlay,
         targetedMessage,
         thread,

package/src/contexts/channelContext/ChannelContext.tsx

@@ -112,6 +112,12 @@ export type ChannelContextValue = {
   setChannelUnreadState: (data: ChannelUnreadStateStoreType['channelUnreadState']) => void;
   setLastRead: React.Dispatch<React.SetStateAction<Date | undefined>>;
   setTargetedMessage: (messageId?: string) => void;
+  /**
+   * Returns true when Channel is about to load an initial targeted message.
+   *
+   * @internal
+   */
+  hasPendingInitialTargetLoad?: () => boolean;
   /**
    * Abort controller for cancelling async requests made for uploading images/files
    * Its a map of filename and AbortController