@assistant-ui/react-native 0.1.45 → 0.1.46

package/src/primitives/thread/ThreadMessages.test.tsx

@@ -10,13 +10,18 @@ type Msg = { id: string; role: string };
 
 const h = vi.hoisted(() => ({
   state: {
-    thread: { messages: [] as Msg[] },
+    thread: {
+      messages: [] as Msg[],
+      hasEarlier: false,
+      isLoadingEarlier: false,
+    },
     message: { role: "user" as string, composer: { isEditing: false } },
   },
   itemState: { role: "user" } as { role: string; parts?: unknown[] },
   events: {} as Record<string, Set<() => void>>,
   flatListProps: null as Record<string, unknown> | null,
   scrollToOffset: vi.fn(),
+  loadEarlier: vi.fn(async () => {}),
 }));
 
 vi.mock("react-native", async (importOriginal) => {
@@ -79,7 +84,9 @@ vi.mock("react-native", async (importOriginal) => {
 vi.mock("@assistant-ui/store", async () => {
   const React = await import("react");
 
+  const aui = { thread: { loadEarlier: h.loadEarlier } };
   return {
+    useAui: () => aui,
     useAuiState: <T,>(selector: (s: typeof h.state) => T) => selector(h.state),
     useAuiEvent: (
       selector: string | { scope: string; event: string },
@@ -400,6 +407,26 @@ describe("ThreadMessages", () => {
   });
 
   describe("MessagesFlatList history", () => {
+    it("pages through the runtime when no history prop is given", async () => {
+      h.state.thread.hasEarlier = true;
+      try {
+        await mountFlatList({ components: messageComponents });
+        getFlatListProps().onStartReached?.({ distanceFromStart: 0 });
+        expect(h.loadEarlier).toHaveBeenCalledOnce();
+
+        h.state.thread.isLoadingEarlier = true;
+        await mountFlatList({ components: messageComponents });
+        expect(getFlatListProps().onStartReached).toBeUndefined();
+      } finally {
+        h.state.thread.hasEarlier = false;
+        h.state.thread.isLoadingEarlier = false;
+      }
+
+      await mountFlatList({ components: messageComponents });
+      expect(getFlatListProps().onStartReached).toBeUndefined();
+      expect(getFlatListProps().onStartReachedThreshold).toBeUndefined();
+    });
+
     it("wires loadMore only while history can load more", async () => {
       const loadMore = vi.fn();
 

package/src/primitives/thread/ThreadMessages.tsx

@@ -1,30 +1,25 @@
 import {
   type ComponentType,
   type FC,
-  type ForwardedRef,
   type ReactNode,
-  type RefObject,
   forwardRef,
   memo,
   useCallback,
-  useEffect,
-  useRef,
 } from "react";
-import {
-  FlatList,
-  type FlatListProps,
-  type LayoutChangeEvent,
-  type NativeScrollEvent,
-  type NativeSyntheticEvent,
-} from "react-native";
+import { FlatList, type FlatListProps } from "react-native";
 import type { ThreadMessage } from "@assistant-ui/core";
 import type { MessageState } from "@assistant-ui/core/store";
-import {
-  RenderChildrenWithAccessor,
-  useAuiEvent,
-  useAuiState,
-} from "@assistant-ui/store";
+import { RenderChildrenWithAccessor, useAuiState } from "@assistant-ui/store";
 import { MessageByIndexProvider } from "@assistant-ui/core/react";
+import {
+  type FlatListHistory,
+  getFlatListPagingProps,
+  useComposedFlatListRef,
+  useFlatListAutoScroll,
+  useFlatListScrollProps,
+  useHistoryLoad,
+  useThreadHistory,
+} from "./flatListScroll";
 
 type MessageComponents =
   | {
@@ -68,56 +63,18 @@ export type ThreadMessagesFlatListProps = Omit<
     scrollToBottomOnRunStart?: boolean | undefined;
     scrollToBottomOnInitialize?: boolean | undefined;
     scrollToBottomOnThreadSwitch?: boolean | undefined;
-    history?:
-      | {
-          hasMore: boolean;
-          isLoadingMore: boolean;
-          loadMore: () => void;
-        }
-      | undefined;
+    /**
+     * Pages older messages in when the list nears its start. Defaults to the
+     * runtime's `thread.hasEarlier` / `isLoadingEarlier` / `loadEarlier()`;
+     * pass it to drive paging from app state instead.
+     */
+    history?: FlatListHistory | undefined;
   };
 
 /** @deprecated Use ThreadMessagesFlatListProps instead. */
 export type ThreadMessagesProps = ThreadMessagesFlatListProps;
 
 const DEFAULT_SYSTEM_MESSAGE = () => null;
-const AT_BOTTOM_THRESHOLD = 4;
-
-const useHistoryLoad = (
-  history: ThreadMessagesFlatListProps["history"],
-  onStartReached: FlatListProps<ThreadMessage>["onStartReached"],
-) => {
-  const loadRequestedRef = useRef(false);
-  const hasMore = history?.hasMore ?? false;
-  const isLoadingMore = history?.isLoadingMore ?? false;
-
-  // The latch is scoped to one commit so a no-op load cannot disable paging.
-  useEffect(() => {
-    loadRequestedRef.current = isLoadingMore;
-  });
-
-  const handleStartReached = useCallback<
-    NonNullable<FlatListProps<ThreadMessage>["onStartReached"]>
-  >(
-    (info) => {
-      onStartReached?.(info);
-      if (loadRequestedRef.current) return;
-      loadRequestedRef.current = true;
-      try {
-        history?.loadMore();
-      } catch (error) {
-        loadRequestedRef.current = false;
-        throw error;
-      }
-    },
-    [history, onStartReached],
-  );
-
-  return {
-    canLoadMore: hasMore && !isLoadingMore,
-    handleStartReached,
-  };
-};
 
 const getComponent = (
   components: MessageComponents,
@@ -223,230 +180,6 @@ const ThreadMessageByChildren = memo(
 );
 ThreadMessageByChildren.displayName = "ThreadPrimitive.MessageByChildren";
 
-const setForwardedRef = <T,>(ref: ForwardedRef<T>, value: T | null) => {
-  if (typeof ref === "function") {
-    ref(value);
-  } else if (ref) {
-    ref.current = value;
-  }
-};
-
-const useComposedFlatListRef = (
-  forwardedRef: ForwardedRef<FlatList<ThreadMessage>>,
-) => {
-  const flatListRef = useRef<FlatList<ThreadMessage> | null>(null);
-
-  const setFlatListRef = useCallback(
-    (node: FlatList<ThreadMessage> | null) => {
-      flatListRef.current = node;
-      setForwardedRef(forwardedRef, node);
-    },
-    [forwardedRef],
-  );
-
-  return [flatListRef, setFlatListRef] as const;
-};
-
-const useThreadMessagesFlatListAutoScroll = ({
-  flatListRef,
-  hasMessages,
-  horizontal = false,
-  autoScroll = true,
-  scrollToBottomOnRunStart = true,
-  scrollToBottomOnInitialize = true,
-  scrollToBottomOnThreadSwitch = true,
-}: {
-  flatListRef: RefObject<FlatList<ThreadMessage> | null>;
-  hasMessages: boolean;
-  horizontal?: boolean | null | undefined;
-  autoScroll?: boolean | undefined;
-  scrollToBottomOnRunStart?: boolean | undefined;
-  scrollToBottomOnInitialize?: boolean | undefined;
-  scrollToBottomOnThreadSwitch?: boolean | undefined;
-}) => {
-  const metricsRef = useRef({
-    contentHeight: 0,
-    viewportHeight: 0,
-    scrollY: 0,
-  });
-  const isAtBottomRef = useRef(true);
-  const lastScrollEventOffsetRef = useRef(0);
-  const initializeScrollRequestedRef = useRef(false);
-  const contentSizeVersionRef = useRef(0);
-  const pendingScrollToBottomRef = useRef<
-    | false
-    | {
-        animated: boolean;
-        minimumContentSizeVersion: number;
-      }
-  >(false);
-
-  const updateIsAtBottom = useCallback(() => {
-    const { contentHeight, scrollY, viewportHeight } = metricsRef.current;
-    isAtBottomRef.current =
-      contentHeight <= viewportHeight ||
-      contentHeight - scrollY - viewportHeight <= AT_BOTTOM_THRESHOLD;
-  }, []);
-
-  // Commanding a scroll records the intended position immediately; the
-  // native scroll echo is bridged and throttled, so waiting for it lets a
-  // fast stream observe stale metrics and drop out of following.
-  const scrollToBottom = useCallback(
-    (animated: boolean) => {
-      const { contentHeight, viewportHeight } = metricsRef.current;
-      const offset = Math.max(0, contentHeight - viewportHeight);
-      metricsRef.current.scrollY = offset;
-      isAtBottomRef.current = true;
-      flatListRef.current?.scrollToOffset({ offset, animated });
-    },
-    [flatListRef],
-  );
-
-  const handleLayout = useCallback(
-    (event: LayoutChangeEvent) => {
-      const wasAtBottom = isAtBottomRef.current;
-      const previousViewportHeight = metricsRef.current.viewportHeight;
-      const viewportHeight = horizontal
-        ? event.nativeEvent.layout.width
-        : event.nativeEvent.layout.height;
-      metricsRef.current.viewportHeight = viewportHeight;
-      updateIsAtBottom();
-      const pending = pendingScrollToBottomRef.current;
-      if (
-        pending &&
-        contentSizeVersionRef.current >= pending.minimumContentSizeVersion &&
-        viewportHeight > 0
-      ) {
-        pendingScrollToBottomRef.current = false;
-        scrollToBottom(pending.animated);
-        return;
-      }
-      if (!wasAtBottom) return;
-      // Layout changes are never user gestures, so they must not unpin. Past
-      // the first measurement, a viewport change while pinned re-commands the
-      // bottom position, since no content-size event follows a bare keyboard
-      // open or close.
-      if (
-        autoScroll &&
-        previousViewportHeight !== 0 &&
-        viewportHeight !== previousViewportHeight
-      ) {
-        scrollToBottom(pending ? pending.animated : false);
-      } else {
-        isAtBottomRef.current = true;
-      }
-    },
-    [autoScroll, horizontal, scrollToBottom, updateIsAtBottom],
-  );
-
-  const handleScroll = useCallback(
-    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-      const { contentOffset, contentSize, layoutMeasurement } =
-        event.nativeEvent;
-      const scrollOffset = horizontal ? contentOffset.x : contentOffset.y;
-      const previousEventOffset = lastScrollEventOffsetRef.current;
-      const wasPinnedToBottom = isAtBottomRef.current;
-      lastScrollEventOffsetRef.current = scrollOffset;
-      metricsRef.current = {
-        contentHeight: horizontal ? contentSize.width : contentSize.height,
-        viewportHeight: horizontal
-          ? layoutMeasurement.width
-          : layoutMeasurement.height,
-        scrollY: scrollOffset,
-      };
-      updateIsAtBottom();
-      const upwardMove = scrollOffset < previousEventOffset;
-      // Only a deliberate upward move unpins or cancels a pending scroll.
-      // Gestures are detected echo-to-echo because a commanded scroll
-      // optimistically moves the tracked position ahead of its ascending
-      // animation echoes, and those echoes must not unpin mid-flight.
-      if (wasPinnedToBottom && !upwardMove) {
-        isAtBottomRef.current = true;
-      }
-      if (!isAtBottomRef.current && upwardMove) {
-        pendingScrollToBottomRef.current = false;
-      }
-    },
-    [horizontal, updateIsAtBottom],
-  );
-
-  const handleContentSizeChange = useCallback(
-    (width: number, height: number) => {
-      const metrics = metricsRef.current;
-      const contentHeight = horizontal ? width : height;
-      const previousContentHeight = metrics.contentHeight;
-      const wasAtBottom = isAtBottomRef.current;
-      if (contentHeight > 0) contentSizeVersionRef.current += 1;
-      metrics.contentHeight = contentHeight;
-      updateIsAtBottom();
-
-      // Initialize and thread-switch requests are repeated after the list has
-      // measured so the explicit bottom offset uses real content metrics.
-      const pendingScroll = pendingScrollToBottomRef.current;
-      if (
-        pendingScroll &&
-        contentSizeVersionRef.current >=
-          pendingScroll.minimumContentSizeVersion &&
-        metrics.viewportHeight > 0
-      ) {
-        pendingScrollToBottomRef.current = false;
-        scrollToBottom(pendingScroll.animated);
-        return;
-      }
-
-      if (!autoScroll) return;
-      if (!wasAtBottom) return;
-      if (previousContentHeight === 0) return;
-      if (contentHeight <= previousContentHeight) return;
-
-      scrollToBottom(false);
-    },
-    [autoScroll, horizontal, scrollToBottom, updateIsAtBottom],
-  );
-
-  useEffect(() => {
-    if (!scrollToBottomOnInitialize) return;
-    if (!hasMessages) {
-      initializeScrollRequestedRef.current = false;
-      return;
-    }
-    if (initializeScrollRequestedRef.current) return;
-
-    initializeScrollRequestedRef.current = true;
-    pendingScrollToBottomRef.current = {
-      animated: false,
-      minimumContentSizeVersion: Math.max(1, contentSizeVersionRef.current),
-    };
-    scrollToBottom(false);
-  }, [hasMessages, scrollToBottom, scrollToBottomOnInitialize]);
-
-  useAuiEvent("thread.runStart", () => {
-    if (!scrollToBottomOnRunStart) return;
-    pendingScrollToBottomRef.current = {
-      animated: true,
-      minimumContentSizeVersion: contentSizeVersionRef.current + 1,
-    };
-    scrollToBottom(true);
-  });
-
-  useAuiEvent("threads.selectionChanged", () => {
-    if (!scrollToBottomOnThreadSwitch) return;
-    initializeScrollRequestedRef.current = false;
-    lastScrollEventOffsetRef.current = 0;
-    pendingScrollToBottomRef.current = {
-      animated: false,
-      minimumContentSizeVersion: contentSizeVersionRef.current + 1,
-    };
-    scrollToBottom(false);
-  });
-
-  return {
-    handleLayout,
-    handleScroll,
-    handleContentSizeChange,
-  };
-};
-
 export const ThreadMessagesFlatList = forwardRef<
   FlatList<ThreadMessage>,
   ThreadMessagesFlatListProps
@@ -461,6 +194,8 @@ export const ThreadMessagesFlatList = forwardRef<
       onScroll,
       onStartReached,
       onStartReachedThreshold,
+      onEndReached,
+      onEndReachedThreshold,
       scrollEventThrottle,
       scrollToBottomOnInitialize,
       scrollToBottomOnRunStart,
@@ -471,12 +206,13 @@ export const ThreadMessagesFlatList = forwardRef<
     forwardedRef,
   ) => {
     const messages = useAuiState((s) => s.thread.messages);
+    const effectiveHistory = useThreadHistory(history);
     const [flatListRef, setFlatListRef] = useComposedFlatListRef(forwardedRef);
     const {
       handleContentSizeChange: handleAutoScrollContentSizeChange,
       handleLayout: handleAutoScrollLayout,
       handleScroll: handleAutoScrollScroll,
-    } = useThreadMessagesFlatListAutoScroll({
+    } = useFlatListAutoScroll({
       flatListRef,
       hasMessages: messages.length > 0,
       horizontal: flatListProps.horizontal,
@@ -502,39 +238,35 @@ export const ThreadMessagesFlatList = forwardRef<
 
     const keyExtractor = useCallback((item: ThreadMessage) => item.id, []);
 
-    const scrollTracking =
-      (autoScroll ?? true) ||
-      (scrollToBottomOnInitialize ?? true) ||
-      (scrollToBottomOnRunStart ?? true) ||
-      (scrollToBottomOnThreadSwitch ?? true);
-
-    const handleLayout = useCallback(
-      (event: LayoutChangeEvent) => {
-        handleAutoScrollLayout(event);
-        onLayout?.(event);
-      },
-      [handleAutoScrollLayout, onLayout],
-    );
+    const scrollProps = useFlatListScrollProps({
+      autoScroll,
+      scrollToBottomOnInitialize,
+      scrollToBottomOnRunStart,
+      scrollToBottomOnThreadSwitch,
+      onContentSizeChange,
+      onLayout,
+      onScroll,
+      scrollEventThrottle,
+      handleAutoScrollContentSizeChange,
+      handleAutoScrollLayout,
+      handleAutoScrollScroll,
+    });
 
-    const handleScroll = useCallback(
-      (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-        handleAutoScrollScroll(event);
-        onScroll?.(event);
-      },
-      [handleAutoScrollScroll, onScroll],
+    const { canLoadMore, handleReached } = useHistoryLoad(
+      effectiveHistory,
+      onStartReached,
     );
-
-    const handleContentSizeChange = useCallback(
-      (width: number, height: number) => {
-        handleAutoScrollContentSizeChange(width, height);
-        onContentSizeChange?.(width, height);
+    const pagingProps = getFlatListPagingProps(
+      "start",
+      effectiveHistory,
+      canLoadMore,
+      handleReached,
+      {
+        onStartReached,
+        onStartReachedThreshold,
+        onEndReached,
+        onEndReachedThreshold,
       },
-      [handleAutoScrollContentSizeChange, onContentSizeChange],
-    );
-
-    const { canLoadMore, handleStartReached } = useHistoryLoad(
-      history,
-      onStartReached,
     );
 
     return (
@@ -544,34 +276,8 @@ export const ThreadMessagesFlatList = forwardRef<
         renderItem={renderItem}
         keyExtractor={keyExtractor}
         maintainVisibleContentPosition={{ minIndexForVisible: 0 }}
-        {...(scrollTracking
-          ? {
-              onContentSizeChange: handleContentSizeChange,
-              onLayout: handleLayout,
-              onScroll: handleScroll,
-              scrollEventThrottle: scrollEventThrottle ?? 16,
-            }
-          : {
-              ...(onContentSizeChange && { onContentSizeChange }),
-              ...(onLayout && { onLayout }),
-              ...(onScroll && { onScroll }),
-              ...(scrollEventThrottle !== undefined && { scrollEventThrottle }),
-            })}
-        {...(history
-          ? {
-              ...(canLoadMore
-                ? { onStartReached: handleStartReached }
-                : onStartReached
-                  ? { onStartReached }
-                  : {}),
-              onStartReachedThreshold: onStartReachedThreshold ?? 1,
-            }
-          : {
-              ...(onStartReached && { onStartReached }),
-              ...(onStartReachedThreshold !== undefined && {
-                onStartReachedThreshold,
-              }),
-            })}
+        {...scrollProps}
+        {...pagingProps}
         {...flatListProps}
       />
     );