feat(ai-conversation): add conditional autoScroll handling (#6551)

Author: calebpollman

.changeset/brave-bears-teach.md

@@ -0,0 +1,5 @@
+---
+"@aws-amplify/ui-react-ai": minor
+---
+
+feat(ai-conversation): add conditional autoScroll handling

packages/react-ai/src/components/AIConversation/AIConversation.tsx

@@ -1,10 +1,13 @@
 import * as React from 'react';
+
 import { Flex, ScrollView } from '@aws-amplify/ui-react';
 import {
   IconAssistant,
   IconUser,
   useIcons,
 } from '@aws-amplify/ui-react/internal';
+
+import useConversationScrollProps from './useConversationScrollProps';
 import type {
   AIConversation as AIConversationType,
   AIConversationInput,
@@ -29,6 +32,7 @@ interface AIConversationBaseProps
 function AIConversationBase({
   avatars,
   controls,
+  messages,
   ...rest
 }: AIConversationBaseProps): React.JSX.Element {
   useSetUserAgent({
@@ -51,25 +55,20 @@ function AIConversationBase({
 
   const providerProps = {
     ...rest,
-    avatars: {
-      ...defaultAvatars,
-      ...avatars,
-    },
-    controls: {
-      MessageList,
-      PromptList,
-      Form,
-      ...controls,
-    },
+    avatars: { ...defaultAvatars, ...avatars },
+    controls: { MessageList, PromptList, Form, ...controls },
+    messages,
   };
 
+  const scrollProps = useConversationScrollProps(messages);
+
   return (
     <AIConversationProvider {...providerProps}>
       <Flex
         className={ComponentClassName.AIConversation}
         testId="ai-conversation"
       >
-        <ScrollView autoScroll="smooth" flex="1">
+        <ScrollView {...scrollProps} flex="1">
           <DefaultMessageControl />
           <MessagesControl />
         </ScrollView>

packages/react-ai/src/components/AIConversation/__tests__/useConversationScrollProps.test.ts

@@ -0,0 +1,57 @@
+import { act, renderHook } from '@testing-library/react';
+import useShouldAutoScroll from '../useConversationScrollProps';
+import { ConversationMessage } from '../../../types';
+
+const messages: ConversationMessage[] = [];
+
+type ScrollEvent = React.UIEvent<HTMLDivElement>;
+
+describe('useShouldAutoScroll', () => {
+  it('returns the expected values on mount', () => {
+    const { result } = renderHook(() => useShouldAutoScroll(messages));
+
+    const { autoScroll, onScroll } = result.current;
+
+    expect(autoScroll).toBe('smooth');
+    expect(onScroll).toStrictEqual(expect.any(Function));
+  });
+
+  it('returns the expected values on messages length change', () => {
+    const { result, rerender } = renderHook(
+      (_messages: ConversationMessage[] = messages) =>
+        useShouldAutoScroll(_messages)
+    );
+
+    const { autoScroll: initAutoScroll, onScroll } = result.current;
+
+    expect(initAutoScroll).toBe('smooth');
+
+    const scrollStartEvent = {
+      currentTarget: { scrollTop: 120 },
+    } as ScrollEvent;
+
+    act(() => {
+      onScroll?.(scrollStartEvent);
+    });
+
+    const { autoScroll: startAutoScroll } = result.current;
+    expect(startAutoScroll).toBe('smooth');
+
+    const scrollUpEvent = { currentTarget: { scrollTop: 119 } } as ScrollEvent;
+
+    act(() => {
+      onScroll?.(scrollUpEvent);
+    });
+
+    const { autoScroll: disabledAutoScroll } = result.current;
+
+    expect(disabledAutoScroll).toBeUndefined();
+
+    // increase `messages` length
+    rerender([...messages, {} as ConversationMessage]);
+
+    const { autoScroll: nextMessagesAutoScroll } = result.current;
+
+    expect(nextMessagesAutoScroll).toBe('smooth');
+  });
+});

packages/react-ai/src/components/AIConversation/useConversationScrollProps.ts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+
+import type { ScrollViewProps } from '@aws-amplify/ui-react';
+import { useHasValueUpdated } from '@aws-amplify/ui-react-core';
+
+import type { ConversationMessage } from '../../types';
+
+interface ConverationScrollProps
+  extends Pick<ScrollViewProps, 'onScroll' | 'autoScroll'> {}
+
+export default function useConversationScrollProps(
+  messages: ConversationMessage[]
+): ConverationScrollProps {
+  const [autoScroll, setAutoScroll] =
+    React.useState<ConverationScrollProps['autoScroll']>('smooth');
+
+  const messagesLength = messages.length;
+  const hasMessagesLengthChanged = useHasValueUpdated(messagesLength, true);
+
+  const lastScrollTop = React.useRef<number | undefined>();
+
+  const onScroll: ConverationScrollProps['onScroll'] = ({ currentTarget }) => {
+    if (autoScroll !== 'smooth') return;
+
+    const { scrollTop } = currentTarget;
+
+    // set `autoScroll` and `lastScrollTop` to `undefined` on user scroll up
+    if (lastScrollTop.current && scrollTop < lastScrollTop.current) {
+      setAutoScroll(undefined);
+      lastScrollTop.current = undefined;
+    } else {
+      lastScrollTop.current = scrollTop;
+    }
+  };
+
+  React.useEffect(() => {
+    // reset `autoScroll` to 'smooth' on new message
+    if (hasMessagesLengthChanged) {
+      setAutoScroll('smooth');
+    }
+  }, [hasMessagesLengthChanged]);
+
+  return { autoScroll, onScroll };
+}