stream-chat-react-native-core 9.12.1 → 9.14.0

package/src/ai-components/conversation/list/useLoadOlder.ts

@@ -0,0 +1,97 @@
+import { type RefObject, useCallback, useEffect, useRef } from 'react';
+
+import type { LegendListRef } from '@legendapp/list/react-native';
+
+// How long the spinner above the turns stays in view before older messages load, so a list that
+// opens at its end does not load for the frame its start shows.
+const LOAD_OLDER_DELAY_MS = 300;
+// How long to wait before asking again after loading older messages failed.
+const LOAD_OLDER_RETRY_MS = 3000;
+// How close to the start, as a share of the list's height, the spinner counts as in view.
+const START_THRESHOLD = 0.1;
+
+export type UseLoadOlderOptions = {
+  listRef: RefObject<LegendListRef | null>;
+  /** Loads the rows before the first one. `undefined` once there are none left. */
+  loadOlderMessages?: () => Promise<void> | void;
+};
+
+/**
+ * Loads older messages once the spinner above the turns has been in view a moment, and again
+ * while it stays in view after a load that failed, or brought nothing while there is more. Only
+ * while the list is at rest: on iOS, what arrives above while a finger holds the list, or while
+ * it glides or bounces, pushes what is in view down rather than staying out of sight.
+ *
+ * Returns the list's handlers for it, or none while there is nothing to load.
+ */
+export const useLoadOlder = ({ listRef, loadOlderMessages }: UseLoadOlderOptions) => {
+  const dragging = useRef(false);
+  const gliding = useRef(false);
+  const loadOlderRef = useRef(loadOlderMessages);
+  loadOlderRef.current = loadOlderMessages;
+  const loading = useRef(false);
+  const loadTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const mounted = useRef(true);
+  const scheduleLoadOlder = useCallback(
+    (delay: number) => {
+      clearTimeout(loadTimer.current);
+      loadTimer.current = setTimeout(async () => {
+        const load = loadOlderRef.current;
+        if (dragging.current || gliding.current) return;
+        if (loading.current || !load || !listRef.current?.getState().isNearStart) return;
+        loading.current = true;
+        let failed = false;
+        try {
+          await load();
+        } catch {
+          failed = true;
+        }
+        loading.current = false;
+        if (mounted.current) {
+          scheduleLoadOlder(failed ? LOAD_OLDER_RETRY_MS : LOAD_OLDER_DELAY_MS);
+        }
+      }, delay);
+    },
+    [listRef],
+  );
+  const onStartReached = useCallback(
+    () => scheduleLoadOlder(LOAD_OLDER_DELAY_MS),
+    [scheduleLoadOlder],
+  );
+  // When the list comes to rest, a load the spinner asked for while it moved goes ahead. A glide
+  // that follows the drag starts before the delay is up, and asks again when it ends.
+  // A drag that stops a glide ends it, which may not say so itself.
+  const onScrollBeginDrag = useCallback(() => {
+    dragging.current = true;
+    gliding.current = false;
+  }, []);
+  const onScrollEndDrag = useCallback(() => {
+    dragging.current = false;
+    scheduleLoadOlder(LOAD_OLDER_DELAY_MS);
+  }, [scheduleLoadOlder]);
+  const onMomentumScrollBegin = useCallback(() => {
+    gliding.current = true;
+  }, []);
+  const onMomentumScrollEnd = useCallback(() => {
+    gliding.current = false;
+    scheduleLoadOlder(LOAD_OLDER_DELAY_MS);
+  }, [scheduleLoadOlder]);
+
+  useEffect(
+    () => () => {
+      mounted.current = false;
+      clearTimeout(loadTimer.current);
+    },
+    [],
+  );
+
+  if (!loadOlderMessages) return undefined;
+  return {
+    onMomentumScrollBegin,
+    onMomentumScrollEnd,
+    onScrollBeginDrag,
+    onScrollEndDrag,
+    onStartReached,
+    onStartReachedThreshold: START_THRESHOLD,
+  };
+};

package/src/ai-components/conversation/list/usePinnedAnchor.ts

@@ -0,0 +1,113 @@
+import { type RefObject, useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+
+import type { AnchoredEndSpaceConfig, LegendListRef } from '@legendapp/list/react-native';
+
+import { useReduceMotion } from '../../voice-visualization/useReduceMotion';
+
+export type UsePinnedAnchorOptions<T> = {
+  /** The key of the row to pin to the top, such as the latest question's. */
+  anchorKey: string | undefined;
+  data: readonly T[];
+  /** The height of the list's header, which its positions leave out. */
+  headerSize: RefObject<number>;
+  keyExtractor: (item: T) => string;
+  listRef: RefObject<LegendListRef | null>;
+  /** Called once the anchor is laid out, and whenever the room the list leaves under it changes. */
+  onAnchorLayout?: () => void;
+};
+
+/**
+ * Pins a row to the top of what is visible: the list leaves room under it (`anchoredEndSpace`),
+ * and a new anchor is scrolled to once it is laid out. The keyboard-aware list keeps that room as
+ * the scroll view's inset, which follows what is below the row shrinking, and which the keyboard
+ * takes before it lifts anything.
+ */
+export const usePinnedAnchor = <T>({
+  anchorKey,
+  data,
+  headerSize,
+  keyExtractor,
+  listRef,
+  onAnchorLayout,
+}: UsePinnedAnchorOptions<T>) => {
+  const reduceMotion = useReduceMotion();
+  const onAnchorLayoutRef = useRef(onAnchorLayout);
+  onAnchorLayoutRef.current = onAnchorLayout;
+
+  // Where to scroll once the anchor is laid out: a new question pins to the top, and a
+  // conversation replaced as a whole opens at its end.
+  const pendingScroll = useRef<{ animated: boolean; key: string; toEnd: boolean } | undefined>(
+    undefined,
+  );
+  const shown = useRef<{ anchorKey?: string; mounted: boolean }>({ mounted: false });
+  useLayoutEffect(() => {
+    const previous = shown.current;
+    shown.current = { anchorKey, mounted: true };
+    if (!previous.mounted || anchorKey === undefined || anchorKey === previous.anchorKey) {
+      return;
+    }
+    const continues =
+      previous.anchorKey !== undefined &&
+      data.some((item) => keyExtractor(item) === previous.anchorKey);
+    pendingScroll.current = continues
+      ? { animated: !reduceMotion, key: anchorKey, toEnd: false }
+      : { animated: false, key: anchorKey, toEnd: true };
+  }, [anchorKey, data, keyExtractor, reduceMotion]);
+
+  const scrollToPending = useCallback(
+    (key: string | undefined) => {
+      const target = pendingScroll.current;
+      const list = listRef.current;
+      if (!target || !list || key !== target.key) return;
+      pendingScroll.current = undefined;
+      // The keyboard-aware list keeps the room under the anchor as the scroll view's inset, which
+      // it sets on the UI thread a frame or two after the room changes. iOS stops a scroll at the
+      // inset it has when the scroll starts, so a scroll started now stops short of the top.
+      requestAnimationFrame(() =>
+        requestAnimationFrame(() => {
+          const current = listRef.current;
+          if (target.toEnd) {
+            void current?.scrollToEnd({ animated: false });
+            return;
+          }
+          void current?.scrollToKey({
+            animated: target.animated,
+            key: target.key,
+            viewPosition: 0,
+          });
+        }),
+      );
+    },
+    [listRef],
+  );
+
+  // The spinner above the turns: the list's positions leave it out.
+  const onMetricsChange = useCallback(
+    ({ headerSize: size }: { headerSize: number }) => {
+      headerSize.current = size;
+    },
+    [headerSize],
+  );
+
+  const anchorIndex = useMemo(
+    () =>
+      anchorKey === undefined ? -1 : data.findIndex((item) => keyExtractor(item) === anchorKey),
+    [anchorKey, data, keyExtractor],
+  );
+  const anchoredEndSpace = useMemo<AnchoredEndSpaceConfig | undefined>(
+    () =>
+      anchorIndex >= 0
+        ? {
+            anchorIndex,
+            onReady: ({ anchorKey: readyKey }) => {
+              scrollToPending(readyKey);
+              onAnchorLayoutRef.current?.();
+            },
+            onSizeChanged: () => onAnchorLayoutRef.current?.(),
+          }
+        : undefined,
+    [anchorIndex, scrollToPending],
+  );
+
+  return { anchoredEndSpace, onMetricsChange };
+};

package/src/ai-components/conversation/useConversationRows.ts

@@ -0,0 +1,231 @@
+import { type ReactNode, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+import {
+  type AIConversationCanShowUI,
+  type AIConversationEntry,
+  type AIConversationTurn,
+  AIPendingMessageTracker,
+  hasFinishedSteps,
+  turnsOf,
+} from './entries';
+
+import type { AIMessage, AIPendingMessage } from '../conversation-state/types';
+
+import type { AIMessageAttachmentData } from '../message/AIMessageAttachment';
+import { AIThinkingClock } from '../reasoning/thinkingClock';
+
+/**
+ * Where a row is: the first of a turn, or within one. The first turn has the same room above it as
+ * the others, so older messages arriving above it leave it where it is.
+ */
+export type RowPosition = 'turn' | 'message';
+
+/** A row of the list: one message, with the turn it belongs to. */
+export type EntryRow = {
+  entry: AIConversationEntry;
+  key: string;
+  kind: 'entry';
+  position: RowPosition;
+  turnKey: string;
+  /** The turn's first reasoning step, which takes over the seconds the turn was seen thinking. */
+  firstStepId?: string;
+  /**
+   * When the agent started thinking again between the steps of this reply, which is being
+   * written, and which its seconds count from. It thinks under the reply, in the reply's row, so
+   * it moves with the reply's steps as they fold.
+   */
+  thinkingSince?: number;
+};
+
+/**
+ * What ends the latest turn: the agent thinking, and the app's footer. A row of its own rather than
+ * the list's footer: the list lays its rows out itself, together with the room it leaves under the
+ * latest turn, while a footer that goes away shrinks the content at once, which moves the view.
+ */
+export type TailRow = {
+  isThinking: boolean;
+  key: string;
+  kind: 'tail';
+  turnKey: string;
+  firstStepId?: string;
+  footer?: ReactNode;
+};
+
+export type ConversationRow = EntryRow | TailRow;
+
+const TAIL_KEY = 'ai-conversation-tail';
+
+// What the latest message was at the last render, to tell whether its answer grew since, and when
+// the agent started thinking between its steps, if it is.
+type BetweenSteps = {
+  messageId: string | undefined;
+  textLength: number;
+  since?: number;
+  stepsKey?: string;
+};
+
+const sameAttachments = (a: AIMessageAttachmentData[], b: AIMessageAttachmentData[]) =>
+  a === b || (a.length === 0 && b.length === 0);
+
+// Whether a row can be kept as it was: the list renders a row again only for a new item.
+const isSameRow = (row: EntryRow, next: Omit<EntryRow, 'key'>) =>
+  row.entry.message === next.entry.message &&
+  row.entry.pending === next.entry.pending &&
+  row.entry.isLatestReply === next.entry.isLatestReply &&
+  sameAttachments(row.entry.sentAttachments, next.entry.sentAttachments) &&
+  row.firstStepId === next.firstStepId &&
+  row.thinkingSince === next.thinkingSince &&
+  row.position === next.position &&
+  row.turnKey === next.turnKey;
+
+// The turn's first reasoning step, which takes over the seconds the turn was seen thinking.
+const firstStepOf = (turn: AIConversationTurn | undefined) => {
+  for (const { message } of turn?.entries ?? []) {
+    if (!message || message.role === 'user') continue;
+    const step = message.parts?.find((part) => part.reasoning);
+    if (step) return step.id;
+  }
+  return undefined;
+};
+
+export type UseConversationRowsOptions = {
+  messages: AIMessage[];
+  /** Whether a reply's generated UI shows, so a reply that shows only UI has a row. */
+  canShowUI?: AIConversationCanShowUI;
+  footer?: ReactNode;
+  isThinking?: boolean;
+  /** Whether `isThinking` alone says whether the agent is thinking, rather than the rows too. */
+  isThinkingKnown?: boolean;
+  pendingMessage?: AIPendingMessage | null;
+};
+
+export type ConversationRows = {
+  /** The key of the latest turn's first row, which pins to the top: `undefined` with no turns. */
+  anchorKey: string | undefined;
+  /** The turns' thinking clock, for `AIThinkingTurnContext`. */
+  clock: AIThinkingClock;
+  /** The rows to list: each message, then what ends the latest turn while there is any. */
+  rows: ConversationRow[];
+  /** Whether there are no messages to show yet, not even one on its way. */
+  isEmpty: boolean;
+};
+
+/**
+ * The conversation's data, as rows for a list: its messages grouped into turns, a message on its
+ * way until its copy arrives, and what ends the latest turn. Each unchanged row keeps its object,
+ * so the list renders only the rows that changed. Knows nothing about the list itself.
+ */
+export const useConversationRows = ({
+  canShowUI,
+  footer,
+  isThinking = false,
+  isThinkingKnown = false,
+  messages,
+  pendingMessage,
+}: UseConversationRowsOptions): ConversationRows => {
+  const [tracker] = useState(() => new AIPendingMessageTracker());
+  const [clock] = useState(() => new AIThinkingClock());
+
+  const entries = useMemo(
+    () => tracker.entries(messages, pendingMessage, canShowUI),
+    [canShowUI, messages, pendingMessage, tracker],
+  );
+  // after `entries`, which matched the copies
+  const thinking =
+    isThinking ||
+    (!isThinkingKnown && tracker.isAwaitingReply(messages, pendingMessage, canShowUI));
+
+  // The agent thinking again between the latest reply's steps: from the update in which a step
+  // ended without the answer growing, until the answer grows. A step that ends together with more
+  // of the answer means the answer is under way.
+  const lastMessage = messages[messages.length - 1];
+  const stepsKey = hasFinishedSteps(lastMessage, canShowUI)
+    ? `${lastMessage.id}:${lastMessage.parts?.length}`
+    : undefined;
+  // A break the agent's backend adds after what came before a step isn't more of the answer.
+  const textLength = lastMessage?.text.trimEnd().length ?? 0;
+  const [gap, setGap] = useState<BetweenSteps>();
+  if (
+    gap?.messageId !== lastMessage?.id ||
+    gap?.stepsKey !== stepsKey ||
+    gap?.textLength !== textLength
+  ) {
+    const grew = gap?.messageId === lastMessage?.id && textLength > (gap?.textLength ?? 0);
+    setGap({
+      messageId: lastMessage?.id,
+      since:
+        grew || stepsKey === undefined
+          ? undefined
+          : stepsKey === gap?.stepsKey
+            ? gap.since
+            : Date.now(),
+      stepsKey,
+      textLength,
+    });
+  }
+  const thinkingSince = !thinking && stepsKey !== undefined ? gap?.since : undefined;
+  const thinkingReplyId = thinkingSince !== undefined ? lastMessage?.id : undefined;
+  const turns = useMemo(() => turnsOf(entries), [entries]);
+  const latest = turns[turns.length - 1];
+  const latestHasReplies = (latest?.entries.length ?? 0) > 1;
+  const latestFirstStepId = firstStepOf(latest);
+  const latestHasFirstStep = latestFirstStepId !== undefined;
+  // Before the views below read it in their effects and next renders: a turn's thinking starts
+  // and ends once.
+  useLayoutEffect(() => {
+    clock.update(latest?.id, thinking, latestHasReplies, latestHasFirstStep);
+  }, [clock, latest?.id, latestHasFirstStep, latestHasReplies, thinking]);
+
+  // The rows, keeping each unchanged one's object, so the list renders only the rows that changed.
+  const rowCache = useRef(new Map<string, EntryRow>());
+  const entryRows = useMemo(() => {
+    const cache = new Map<string, EntryRow>();
+    const next: EntryRow[] = [];
+    turns.forEach((turn) => {
+      const firstStepId = firstStepOf(turn);
+      turn.entries.forEach((entry, index) => {
+        const fields = {
+          entry,
+          firstStepId,
+          kind: 'entry' as const,
+          position: (index > 0 ? 'message' : 'turn') as RowPosition,
+          thinkingSince:
+            thinkingReplyId !== undefined && entry.message?.id === thinkingReplyId
+              ? thinkingSince
+              : undefined,
+          turnKey: turn.id,
+        };
+        const previous = rowCache.current.get(entry.id);
+        const row =
+          previous && isSameRow(previous, fields) ? previous : { ...fields, key: entry.id };
+        cache.set(entry.id, row);
+        next.push(row);
+      });
+    });
+    rowCache.current = cache;
+    return next;
+  }, [thinkingReplyId, thinkingSince, turns]);
+
+  // A turn's id is its first entry's, so the latest turn's first row has its key.
+  const lastTurnKey = latest?.id;
+  const tailRow = useMemo<TailRow | undefined>(
+    () =>
+      lastTurnKey !== undefined && (thinking || footer)
+        ? {
+            firstStepId: latestFirstStepId,
+            footer,
+            isThinking: thinking,
+            key: TAIL_KEY,
+            kind: 'tail',
+            turnKey: lastTurnKey,
+          }
+        : undefined,
+    [footer, lastTurnKey, latestFirstStepId, thinking],
+  );
+  const rows = useMemo<ConversationRow[]>(
+    () => (tailRow ? [...entryRows, tailRow] : entryRows),
+    [entryRows, tailRow],
+  );
+
+  return { anchorKey: lastTurnKey, clock, isEmpty: entryRows.length === 0, rows };
+};

package/src/ai-components/conversation-state/controller/AIAgentError.ts

@@ -0,0 +1,14 @@
+/**
+ * The agent couldn't answer: it said so, with what it said as `agentMessage`, or it didn't start
+ * its reply in time.
+ */
+export class AIAgentError extends Error {
+  /** What the agent said about it, if anything. */
+  readonly agentMessage?: string;
+
+  constructor(agentMessage?: string) {
+    super(agentMessage || 'The agent couldn’t answer. Try again.');
+    this.name = 'AIAgentError';
+    this.agentMessage = agentMessage || undefined;
+  }
+}